diff --git a/examples/scaffolding/benchmarks/__main__.py b/examples/scaffolding/benchmarks/__main__.py
index 6fc89f696244..d5e5941967b1 100644
--- a/examples/scaffolding/benchmarks/__main__.py
+++ b/examples/scaffolding/benchmarks/__main__.py
@@ -14,6 +14,7 @@
 """
 
 import argparse
+import os
 import sys
 
 from tensorrt_llm.scaffolding import TaskMetricsCollector
@@ -21,6 +22,7 @@
 from .agent_benchmark import async_agent_benchmark, async_burst_agent_benchmark
 from .benchmark_utils import run_benchmark_in_thread
 from .chat_benchmark import async_chat_benchmark
+from .coder_benchmark import async_coder_benchmark
 from .multiround_chat_benchmark import async_multiround_chat_benchmark
 
 
@@ -129,6 +131,68 @@ def parse_arguments():
         help="[Agent only] Enable query collector for debugging",
     )
 
+    # Coder agent parameters
+    parser.add_argument(
+        "--enable_coder",
+        action="store_true",
+        help="Enable Coder agent benchmark (uses Apiary sandboxes via ApiaryMCPWorker)",
+    )
+    parser.add_argument(
+        "--coder_concurrency",
+        type=int,
+        default=32,
+        help="Concurrency for Coder agent benchmark (default: 32)",
+    )
+    parser.add_argument(
+        "--coder_prompt_num",
+        type=int,
+        default=8,
+        help="Number of prompts for Coder benchmark (default: 8)",
+    )
+    parser.add_argument(
+        "--coder_max_iterations",
+        type=int,
+        default=50,
+        help="Max tool-calling iterations per Coder request (default: 50)",
+    )
+    parser.add_argument(
+        "--coder_max_connections",
+        type=int,
+        default=200,
+        help="Max concurrent Apiary sandbox connections for Coder (default: 200)",
+    )
+    parser.add_argument(
+        "--mcp_url",
+        type=str,
+        default="http://0.0.0.0:8083/sse",
+        help="Coder Apiary MCP server URL (default: http://0.0.0.0:8083/sse)",
+    )
+    parser.add_argument(
+        "--coder_image",
+        type=str,
+        default="ubuntu:22.04",
+        help="Docker image name used for Coder benchmark sandboxes (default: ubuntu:22.04)",
+    )
+    parser.add_argument(
+        "--apiary_url",
+        type=str,
+        default=os.getenv("APIARY_URL", "http://127.0.0.1:8080"),
+        help="[Coder only] Apiary daemon URL used to register the sandbox image "
+        "(default: $APIARY_URL or http://127.0.0.1:8080)",
+    )
+    parser.add_argument(
+        "--apiary_token",
+        type=str,
+        default=os.getenv("APIARY_API_TOKEN"),
+        help="[Coder only] Bearer token for the Apiary daemon (default: $APIARY_API_TOKEN)",
+    )
+    parser.add_argument(
+        "--coder_rate",
+        type=float,
+        default=1.0,
+        help="[Rate mode] Poisson arrival rate (req/s) for Coder benchmark. Default: 1.0.",
+    )
+
     # Burst agent parameters
     parser.add_argument(
         "--enable_burst_agent",
@@ -456,6 +520,7 @@ def parse_arguments():
 # Benchmark registry: (async_func, display_name, flag_name)
 BENCHMARK_REGISTRY = [
     (async_agent_benchmark, "Agent-Benchmark", "enable_normal_agent"),
+    (async_coder_benchmark, "Coder-Benchmark", "enable_coder"),
     (async_burst_agent_benchmark, "Burst-Agent-Benchmark", "enable_burst_agent"),
     (async_chat_benchmark, "Chat-Benchmark", "enable_chat"),
     (async_multiround_chat_benchmark, "Multiround-Chat-Benchmark", "enable_multiround_chat"),
@@ -497,8 +562,8 @@ def main():
 
     if not enabled_benchmarks:
         print(
-            "No benchmark enabled. Use --enable_normal_agent, --enable_burst_agent, "
-            "--enable_chat, or --enable_multiround_chat"
+            "No benchmark enabled. Use --enable_normal_agent, --enable_coder, "
+            "--enable_burst_agent, --enable_chat, or --enable_multiround_chat"
         )
         sys.exit(1)
 
diff --git a/examples/scaffolding/benchmarks/coder_benchmark.py b/examples/scaffolding/benchmarks/coder_benchmark.py
new file mode 100644
index 000000000000..5650c5d0d93a
--- /dev/null
+++ b/examples/scaffolding/benchmarks/coder_benchmark.py
@@ -0,0 +1,203 @@
+"""Coder agent benchmark for scaffolding benchmarks.
+
+Runs the Coder agent against Apiary sandboxes with configurable concurrency.
+Each concurrent request gets its own isolated sandbox via ApiaryMCPWorker.
+"""
+
+import sys
+
+from apiary_client import AsyncApiary
+from openai import AsyncOpenAI
+
+from tensorrt_llm.scaffolding import ApiaryMCPWorker, QueryCollector, TRTOpenaiWorker
+from tensorrt_llm.scaffolding.benchmark import ScaffoldingBenchRequest, async_scaffolding_benchmark
+from tensorrt_llm.scaffolding.contrib.Coder import create_coder_scaffolding_llm
+from tensorrt_llm.scaffolding.load_generation_strategy import (
+    ConcurrentStrategy,
+    PoissonRateStrategy,
+    UniformWarmupStrategy,
+)
+
+from .benchmark_utils import print_benchmark_results, print_lock, shutdown_llm
+
+DEFAULT_CODER_PROMPTS = [
+    "Add comprehensive error handling to all public functions in the project.",
+    "Implement a thread-safe LRU cache with configurable capacity.",
+    "Write a CLI tool that converts CSV files to JSON with streaming support.",
+    "Create a retry decorator with exponential backoff and jitter.",
+    "Implement a simple key-value store with TTL-based expiration.",
+    "Add input validation and type checking to the API endpoint handlers.",
+    "Write a log aggregation utility that merges and deduplicates log entries.",
+    "Create a configuration loader that supports YAML, JSON, and environment variables.",
+]
+
+
+def load_coder_prompts(num_prompts: int) -> list[str]:
+    """Load prompts for the Coder benchmark from built-in coding tasks."""
+    prompts = DEFAULT_CODER_PROMPTS.copy()
+    if len(prompts) < num_prompts:
+        original = prompts.copy()
+        repeat = (num_prompts + len(original) - 1) // len(original)
+        prompts = []
+        for i in range(repeat):
+            for p in original:
+                tag = f"[{i}]." if i > 0 else ""
+                prompts.append(f"{tag}{p}")
+    return prompts[:num_prompts]
+
+
+async def register_coder_image(args) -> None:
+    """Register the Coder benchmark image with the Apiary daemon.
+
+    The image used by every benchmark request must be registered before the
+    MCP server creates sandboxes against it (otherwise Apiary returns 404).
+    Failures are surfaced as a hard error so the benchmark doesn't silently
+    produce 502s for every iteration.
+    """
+    image = getattr(args, "coder_image", "ubuntu:22.04")
+    apiary_url = getattr(args, "apiary_url", "http://127.0.0.1:8080")
+    apiary_token = getattr(args, "apiary_token", None)
+
+    apiary = AsyncApiary(
+        apiary_url=apiary_url,
+        apiary_token=apiary_token,
+        images=[image],
+    )
+    try:
+        if not await apiary.health_check(retries=10, interval=1.0):
+            raise RuntimeError(
+                f"Apiary daemon at {apiary_url} is not reachable. "
+                "Start it with `apiary init && apiary daemon --bind ...`."
+            )
+        status = await apiary.load()
+        if status is not None and image in status.failed:
+            reason = next(
+                (
+                    entry.get("reason")
+                    for entry in status.failed_images
+                    if entry.get("name") == image
+                ),
+                "unknown",
+            )
+            raise RuntimeError(f"Failed to register image {image!r} with Apiary: {reason}")
+    finally:
+        await apiary.close()
+
+
+async def create_coder_resources(args):
+    """Create isolated resources for a Coder benchmark run.
+
+    Returns:
+        Tuple of (llm, mcp_worker, generation_worker) for cleanup.
+    """
+    client = AsyncOpenAI(api_key=args.openai_api_key, base_url=args.base_url)
+    generation_worker = TRTOpenaiWorker(
+        client, args.model, getattr(args, "kv_cache_hint_agent", False)
+    )
+
+    mcp_url = getattr(args, "mcp_url", "http://0.0.0.0:8083/sse")
+    max_conns = getattr(args, "coder_max_connections", 200)
+    mcp_worker = ApiaryMCPWorker(mcp_url, max_connections=max_conns)
+
+    llm = create_coder_scaffolding_llm(
+        generation_worker,
+        mcp_worker,
+        max_tokens=getattr(args, "max_tokens_agent", 65536),
+        max_iterations=getattr(args, "coder_max_iterations", 50),
+        max_parallel_requests=getattr(args, "max_parallel_requests", 1024),
+        enable_statistics=getattr(args, "enable_statistics", False),
+    )
+
+    return llm, mcp_worker, generation_worker
+
+
+async def cleanup_coder_resources(llm, mcp_worker):
+    """Cleanup Coder benchmark resources."""
+    await mcp_worker.async_shutdown()
+    await shutdown_llm(llm)
+
+
+async def run_coder_benchmark_core(
+    llm, prompts, concurrency, benchmark_name, args, use_poisson_arrival=True
+):
+    """Core Coder benchmark logic.
+
+    Args:
+        llm: The ScaffoldingLlm instance.
+        prompts: List of prompts to benchmark.
+        concurrency: Number of concurrent requests.
+        benchmark_name: Name for the benchmark (used in output).
+        args: Command line arguments.
+
+    Returns:
+        Tuple of (results, requests_start_time, requests_execution_time, total_time).
+    """
+    task_collection_types = {}
+    requests = [
+        ScaffoldingBenchRequest(
+            prompt=prompt,
+            scope_params={"image": getattr(args, "coder_image", "ubuntu:22.04")},
+        )
+        for prompt in prompts
+    ]
+
+    if use_poisson_arrival and getattr(args, "load_mode", "concurrent") == "rate":
+        strategy = PoissonRateStrategy(
+            rate=getattr(args, "coder_rate", 1.0),
+            random_seed=getattr(args, "rate_seed", 42),
+        )
+    elif getattr(args, "warmup_window", None) is not None:
+        strategy = UniformWarmupStrategy(
+            num_requests=len(requests),
+            warmup_window=args.warmup_window,
+            max_concurrency=concurrency,
+        )
+    else:
+        strategy = ConcurrentStrategy(concurrency=concurrency)
+    print(f"  Strategy: {strategy}")
+
+    (
+        results,
+        requests_start_time,
+        requests_execution_time,
+        total_time,
+    ) = await async_scaffolding_benchmark(llm, task_collection_types, requests, strategy=strategy)
+
+    print_benchmark_results(
+        benchmark_name,
+        results,
+        requests_start_time,
+        requests_execution_time,
+        total_time,
+    )
+
+    if getattr(args, "enable_query_collector", False):
+        QueryCollector.get_global_info()
+        with print_lock:
+            print(f"Query info dumped to query_result.json! ({benchmark_name})")
+
+    return results, requests_start_time, requests_execution_time, total_time
+
+
+async def async_coder_benchmark(args):
+    """Run the Coder agent benchmark.
+
+    Returns:
+        Tuple of (results, requests_start_time, requests_execution_time, total_time).
+    """
+    concurrency = getattr(args, "coder_concurrency", 32)
+    num_prompts = getattr(args, "coder_prompt_num", 8)
+
+    await register_coder_image(args)
+
+    llm, mcp_worker, _ = await create_coder_resources(args)
+    prompts = load_coder_prompts(num_prompts)
+
+    with print_lock:
+        print(f"\n[Coder] Starting benchmark with {num_prompts} prompts, concurrency={concurrency}")
+        sys.stdout.flush()
+
+    try:
+        return await run_coder_benchmark_core(llm, prompts, concurrency, "Coder", args)
+    finally:
+        await cleanup_coder_resources(llm, mcp_worker)
diff --git a/examples/scaffolding/contrib/Coder/README.md b/examples/scaffolding/contrib/Coder/README.md
new file mode 100644
index 000000000000..9593e7114fa1
--- /dev/null
+++ b/examples/scaffolding/contrib/Coder/README.md
@@ -0,0 +1,260 @@
+# Scaffolding Coder Agent
+
+Agentic coding system built on the TensorRT-LLM Scaffolding framework. The Coder agent uses an LLM for reasoning and planning, and executes filesystem and shell operations inside isolated Apiary sandboxes through a dedicated MCP server.
+
+## Architecture
+
+```text
+LLM server <-> ScaffoldingLlm <-> Coder / SWEBenchCoder
+                                 |
+                                 v
+                           ApiaryMCPWorker
+                                 |
+                                 v
+                         examples/.../coder_mcp.py
+                                 |
+                                 v
+                       apiary_client.ApiarySessionMux
+                                 |
+                                 v
+                           Apiary daemon / sessions
+```
+
+Three services are involved:
+
+- Apiary daemon: manages sandbox sessions, image registry (populated at runtime via HTTP), and command execution
+- `coder_mcp.py`: exposes the Coder tool surface over MCP SSE
+- LLM server: OpenAI-compatible endpoint used by Scaffolding
+
+## Tooling Model
+
+The Coder agent expects these MCP tools:
+
+- `read_file`
+- `list_dir`
+- `grep_files`
+- `exec`
+- `shell`
+- `update_plan`
+- `think`
+- `complete_task`
+
+File edits go through `shell` (e.g. `sed -i`, `cat <<'EOF' > path` heredocs, `tee`).
+
+`ApiaryMCPWorker` opens one SSE connection per Scaffolding execution scope, so parallel branches naturally get isolated sandboxes.
+
+## Prerequisites
+
+```bash
+# Apiary Python bindings (shared with coder_mcp, runners, and SWE-bench helpers)
+pip install /path/to/apiary/bindings/python
+```
+
+For HuggingFace SWE-bench datasets, install the `swebench` extra:
+
+```bash
+pip install '/path/to/apiary/bindings/python[swebench]'
+```
+
+## Start Apiary
+
+
+The recommended deployment method is the Apiary container shipped under `/apiary/docker-compose.yml`.
+
+### Container (recommended)
+
+```bash
+cd /path/to/apiary
+
+# Build and start the container; 8080 is exposed on the host by default.
+docker compose up -d
+```
+
+The container's entrypoint runs `apiary init && apiary daemon --bind 0.0.0.0:8080`, leaving you with an empty pool ready to accept image registrations from clients.
+
+Useful environment variables (see the Apiary README for the full list):
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `APIARY_PORT` | `8080` | Host port to publish |
+| `APIARY_BIND` | `0.0.0.0:8080` | Bind address inside the container |
+| `APIARY_API_TOKEN` | (empty) | Bearer token for API auth (empty disables auth) |
+| `APIARY_MAX_SANDBOXES` | `40` | Pool concurrency cap |
+| `APIARY_LAYERS_DIR` | `/var/lib/apiary/layers` | Layer cache (named volume) |
+| `APIARY_OVERLAY_DIR` | `/var/lib/apiary/overlays` | Overlay scratch (named volume) |
+
+Verify from the host:
+
+```bash
+curl -s http://172.17.0.1:8080/healthz       # {"status":"ok"}
+curl -s http://172.17.0.1:8080/api/v1/status # pool counters + registered_images
+```
+
+### Native install
+
+Only needed when Docker is unavailable. Requires Linux 5.11+, cgroups v2 with delegation, and the `uidmap` package.
+
+```bash
+cd /path/to/apiary
+cargo build --release
+
+apiary init --max-sandboxes 40
+apiary daemon --bind 0.0.0.0:8080
+```
+
+The Coder runners (`run_coder.py`, `run_swebench.py`, the benchmark) then register the images they need via `POST /api/v1/images` before they dispatch any work.
+
+## Start the MCP Server
+
+```bash
+python examples/scaffolding/mcp/coder/coder_mcp.py \
+    --apiary-url http://172.17.0.1:8080 \
+    --default-image ubuntu:22.04 \
+    --port 8083
+```
+
+Key flags:
+
+- `--apiary-url` — Apiary daemon URL
+- `--apiary-token` — bearer token for daemon auth
+- `--mcp-token` — bearer token required on the SSE endpoint
+- `--default-image` — fallback Docker image for sandbox sessions when an SSE client omits the `image` query parameter (must already be registered with the daemon)
+- `--working-dir` — default sandbox working directory
+- `--idle-timeout` — idle session reap timeout in seconds
+
+Per-request image selection works through the SSE `image` query parameter. `ApiaryMCPWorker.set_scope_params(..., image=...)` is how the Scaffolding runners select the correct sandbox image for each request. The image is expected to be registered with the daemon already; the runners listed below do that for you.
+
+## Run a Single Coder Task
+
+```bash
+python examples/scaffolding/contrib/Coder/run_coder.py \
+    --base_url http://localhost:8000/v1 \
+    --model Qwen3/Qwen3-30B-A3B \
+    --apiary_url http://172.17.0.1:8080 \
+    --mcp_url http://127.0.0.1:8083/sse \
+    --image ubuntu:22.04 \
+    --prompt "Implement a thread-safe LRU cache in Python" \
+    --max_iterations 50 \
+    --enable_tracing
+```
+
+The runner registers `--image` with the Apiary daemon on startup (via `AsyncApiary`) and only dispatches the request once the image is loaded.
+
+Important flags:
+
+- `--image`: Docker image used for the request's sandbox (auto-registered)
+- `--apiary_url` / `--apiary_token`: How to reach the Apiary daemon for image registration (defaults to `$APIARY_URL` / `$APIARY_API_TOKEN`)
+- `--mcp_url`: `coder_mcp.py` SSE endpoint
+- `--max_mcp_connections`: Max concurrent SSE / sandbox connections
+
+## Run SWE-bench
+
+The runner resolves the SWE-bench image set from the dataset, registers all unique images with the Apiary daemon (with per-image progress logging), and only then starts dispatching agent requests.
+
+```bash
+python examples/scaffolding/contrib/Coder/run_swebench.py \
+    --dataset lite \
+    --split dev \
+    --apiary_url http://172.17.0.1:8080 \
+    --base_url http://localhost:8000/v1 \
+    --model Qwen3/Qwen3-30B-A3B \
+    --mcp_url http://0.0.0.0:8083/sse \
+    --max_parallel_requests 16
+```
+
+Useful flags:
+
+- `--apiary_url` / `--apiary_token`: Apiary daemon target
+- `--apiary_load_timeout`: Bound the wait for image registration (default: no timeout — large SWE-bench splits can take a while on a cold cache)
+
+If the daemon is unreachable the runner aborts immediately with a clear error before any LLM work is dispatched. Per-image failures are logged and surfaced as warnings; only those instances are affected — the rest of the batch still runs against the images that did load.
+
+If you want to pre-load the image set out of band (for example to share a warmed-up daemon across multiple runs), use the `apiary-load-swebench` CLI shipped with `apiary-client[swebench]`:
+
+```bash
+apiary-load-swebench --apiary-url http://172.17.0.1:8080 --dataset lite
+```
+
+The runner is idempotent: already-loaded images are reported as `alreadypresent` and skip the load pipeline.
+
+Outputs:
+
+- `swebench_output/<dataset>-<split>-<model>-<time>/preds.json`: Predictions for SWE-bench evaluation
+- `swebench_output/<dataset>-<split>-<model>-<time>/<instance_id>/<instance_id>.traj.json`: Per-instance trajectory
+- `swebench_output/<dataset>-<split>-<model>-<time>/<instance_id>/<instance_id>.trace.json`: Optional execution trace when `--enable_tracing` is enabled
+
+Pass `--output_dir` to override the default run directory.
+
+## Run the Coder Benchmark
+
+The benchmark harness passes a Docker image name per request through the shared `scope_params` path used by `ApiaryMCPWorker`, and the harness itself registers that image with the Apiary daemon before any benchmark request is dispatched.
+
+```bash
+python -m examples.scaffolding.benchmarks \
+    --model_dir /path/to/model \
+    --base_url http://localhost:8000/v1 \
+    --enable_coder \
+    --coder_image ubuntu:22.04 \
+    --apiary_url http://172.17.0.1:8080 \
+    --coder_concurrency 16 \
+    --coder_prompt_num 8 \
+    --coder_max_iterations 50 \
+    --mcp_url http://0.0.0.0:8083/sse
+```
+
+Coder-specific flags:
+
+- `--coder_image`: Docker image used for benchmark sandboxes (auto-registered)
+- `--apiary_url` / `--apiary_token`: Apiary daemon target for image registration (defaults to `$APIARY_URL` / `$APIARY_API_TOKEN`)
+- `--coder_concurrency`: Number of concurrent requests
+- `--coder_prompt_num`: Number of prompts to run
+- `--coder_max_iterations`: Max tool-calling iterations per request
+- `--coder_max_connections`: Max concurrent Apiary sandbox connections
+
+## Programmatic Usage
+
+```python
+import asyncio
+from apiary_client import AsyncApiary
+from openai import AsyncOpenAI
+from tensorrt_llm.scaffolding import ApiaryMCPWorker, TRTOpenaiWorker
+from tensorrt_llm.scaffolding.contrib.Coder import create_coder_scaffolding_llm
+
+
+async def main() -> None:
+    image = "ubuntu:22.04"
+
+    # 1. Register the image with the Apiary daemon (idempotent).
+    async with AsyncApiary(
+        apiary_url="http://172.17.0.1:8080",
+        images=[image],
+    ) as apiary:
+        assert image in apiary.loaded, f"Apiary failed to load {image}"
+
+    # 2. Now run the Coder agent against the registered image.
+    client = AsyncOpenAI(
+        api_key="tensorrt_llm",
+        base_url="http://localhost:8000/v1",
+    )
+    generation_worker = TRTOpenaiWorker(client, "Qwen3/Qwen3-30B-A3B")
+    mcp_worker = ApiaryMCPWorker("http://0.0.0.0:8083/sse")
+
+    llm = create_coder_scaffolding_llm(
+        generation_worker,
+        mcp_worker,
+        max_tokens=16384,
+        max_iterations=50,
+    )
+
+    result = llm.generate_async("Add input validation to the API handlers")
+    mcp_worker.set_scope_params(result.id, image=image)
+    output = await result.aresult()
+    print(output.outputs[0].text)
+
+    await mcp_worker.async_shutdown()
+    llm.shutdown()
+    generation_worker.shutdown()
+
+
+asyncio.run(main())
+```
diff --git a/examples/scaffolding/contrib/Coder/run_coder.py b/examples/scaffolding/contrib/Coder/run_coder.py
new file mode 100644
index 000000000000..0b7909d3f928
--- /dev/null
+++ b/examples/scaffolding/contrib/Coder/run_coder.py
@@ -0,0 +1,228 @@
+import argparse
+import asyncio
+import io
+import logging
+import os
+from contextlib import redirect_stdout
+from datetime import datetime
+from pathlib import Path
+
+from apiary_client import AsyncApiary
+from openai import AsyncOpenAI
+
+from tensorrt_llm.scaffolding import (
+    ApiaryMCPWorker,
+    QueryCollector,
+    TaskMetricsCollector,
+    TRTOpenaiWorker,
+)
+from tensorrt_llm.scaffolding.contrib.Coder import create_coder_scaffolding_llm
+
+logger = logging.getLogger(__name__)
+
+
+def parse_arguments():
+    parser = argparse.ArgumentParser(
+        description="Run the Coder agent for code generation and modification tasks."
+    )
+    parser.add_argument("--openai_api_key", type=str, default="tensorrt_llm")
+    parser.add_argument("--base_url", type=str, default="http://localhost:8000/v1")
+    parser.add_argument("--model", type=str, default="Qwen3/Qwen3-30B-A3B")
+    parser.add_argument(
+        "--mcp_url",
+        type=str,
+        default="http://0.0.0.0:8086/sse",
+        help="URL for the Coder Apiary MCP server (coder_mcp.py)",
+    )
+    parser.add_argument(
+        "--max_mcp_connections",
+        type=int,
+        default=200,
+        help="Maximum concurrent sandbox connections",
+    )
+    parser.add_argument(
+        "--image",
+        type=str,
+        default="ubuntu:22.04",
+        help="Docker image registered with the Apiary daemon and used for the sandbox session",
+    )
+    parser.add_argument(
+        "--apiary_url",
+        type=str,
+        default=os.getenv("APIARY_URL", "http://172.17.0.1:8080"),
+        help="Apiary daemon URL used to register the sandbox image",
+    )
+    parser.add_argument(
+        "--apiary_token",
+        type=str,
+        default=os.getenv("APIARY_API_TOKEN"),
+        help="Bearer token for the Apiary daemon",
+    )
+    parser.add_argument(
+        "--prompt",
+        type=str,
+        default=None,
+        help="Custom prompt for the Coder agent. If not provided, a default example is used.",
+    )
+    parser.add_argument(
+        "--max_tokens",
+        type=int,
+        default=16384,
+        help="Maximum tokens for generation",
+    )
+    parser.add_argument(
+        "--max_iterations",
+        type=int,
+        default=50,
+        help="Maximum tool-calling iterations",
+    )
+    parser.add_argument("--enable_query_collector", action="store_true")
+    parser.add_argument(
+        "--enable_statistics",
+        action="store_true",
+        help="Print live task metrics and save the final summary as text. Does not write metrics JSON.",
+    )
+    parser.add_argument("--enable_tracing", action="store_true")
+    parser.add_argument(
+        "--trace_output_dir",
+        type=str,
+        default=None,
+        help="Directory for trace outputs when --enable_tracing is set",
+    )
+    return parser.parse_args()
+
+
+def _dump_task_metrics_summary(output_dir: Path) -> None:
+    buf = io.StringIO()
+    with redirect_stdout(buf):
+        TaskMetricsCollector.print_summary()
+    summary = buf.getvalue()
+    print(summary, end="")
+
+    summary_path = output_dir / "coder.metrics.txt"
+    summary_path.write_text(summary, encoding="utf-8")
+    print(f"Task metrics summary saved to {summary_path}")
+
+
+async def register_image(image: str, apiary_url: str, apiary_token: str | None) -> None:
+    """Ensure ``image`` is registered with the Apiary daemon before dispatching work.
+
+    Apiary returns 404 for any session targeting an unregistered image. This
+    helper performs a single-image load via :class:`AsyncApiary` so the MCP
+    server can create sandboxes immediately.
+    """
+    apiary = AsyncApiary(
+        apiary_url=apiary_url,
+        apiary_token=apiary_token,
+        images=[image],
+    )
+    try:
+        if not await apiary.health_check(retries=10, interval=1.0):
+            raise RuntimeError(
+                f"Apiary daemon at {apiary_url} is not reachable. "
+                "Start it with `apiary init && apiary daemon --bind ...`."
+            )
+        status = await apiary.load()
+        if status is not None and image in status.failed:
+            reason = next(
+                (
+                    entry.get("reason")
+                    for entry in status.failed_images
+                    if entry.get("name") == image
+                ),
+                "unknown",
+            )
+            raise RuntimeError(f"Failed to register image {image!r} with Apiary: {reason}")
+        logger.info("Apiary image %s registered", image)
+    finally:
+        await apiary.close()
+
+
+async def main():
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )
+    args = parse_arguments()
+    trace_output_dir: Path | None = None
+    if args.enable_tracing or args.enable_statistics:
+        if args.trace_output_dir:
+            trace_output_dir = Path(args.trace_output_dir)
+        else:
+            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+            trace_output_dir = Path(f"coder_trace_{timestamp}")
+        trace_output_dir.mkdir(parents=True, exist_ok=True)
+
+    await register_image(args.image, args.apiary_url, args.apiary_token)
+
+    client = AsyncOpenAI(api_key=args.openai_api_key, base_url=args.base_url)
+
+    generation_worker = TRTOpenaiWorker(client, args.model)
+
+    mcp_worker = ApiaryMCPWorker(
+        args.mcp_url,
+        max_connections=args.max_mcp_connections,
+    )
+
+    if args.enable_statistics:
+        TaskMetricsCollector.reset()
+        print(
+            "Statistics enabled: "
+            f"model={args.model}, base_url={args.base_url}, max_iterations={args.max_iterations}, "
+            f"max_tokens={args.max_tokens}"
+        )
+
+    llm = create_coder_scaffolding_llm(
+        generation_worker,
+        mcp_worker,
+        max_tokens=args.max_tokens,
+        max_iterations=args.max_iterations,
+        enable_statistics=args.enable_statistics,
+        enable_tracing=args.enable_tracing,
+    )
+
+    if args.prompt:
+        prompt = args.prompt
+    else:
+        prompt = "Implement a collective communication library in C++"
+
+    print(f"Running Coder agent with prompt:\n{prompt}\n")
+    if trace_output_dir is not None:
+        print(f"Trace output directory: {trace_output_dir}")
+    print("-" * 50)
+
+    try:
+        future = llm.generate_async(prompt)
+        mcp_worker.set_scope_params(future.id, image=args.image)
+        result = await future.aresult()
+
+        assert result.outputs[0].text is not None
+        print("\nFinal output:\n" + result.outputs[0].text)
+
+        if args.enable_query_collector:
+            QueryCollector.get_global_info()
+            print("Query info dumped to query_result.json!")
+
+        if args.enable_tracing and result.task_collections:
+            tracer = result.task_collections.get("execution_tracer")
+            if tracer:
+                trace = tracer.export_trace()
+                assert trace_output_dir is not None
+                trace_path = trace_output_dir / "coder.trace.json"
+                full_trace_path = trace_output_dir / "coder.full.trace.json"
+                trace.save(str(trace_path))
+                trace.save(str(full_trace_path), full=True)
+                print(f"Execution trace saved to {trace_path}")
+                print(f"Full execution trace saved to {full_trace_path}")
+    finally:
+        if args.enable_statistics:
+            assert trace_output_dir is not None
+            _dump_task_metrics_summary(trace_output_dir)
+
+        await mcp_worker.async_shutdown()
+        llm.shutdown()
+        generation_worker.shutdown()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/scaffolding/contrib/Coder/run_swebench.py b/examples/scaffolding/contrib/Coder/run_swebench.py
new file mode 100644
index 000000000000..85b45c872f44
--- /dev/null
+++ b/examples/scaffolding/contrib/Coder/run_swebench.py
@@ -0,0 +1,559 @@
+import argparse
+import asyncio
+import json
+import logging
+import os
+import re
+import time
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+from apiary_client import AsyncApiary, ImageJobStatus
+from apiary_client.swebench import get_docker_image, load_instances
+from openai import AsyncOpenAI
+
+from tensorrt_llm.scaffolding import ApiaryMCPWorker, TRTOpenaiWorker
+from tensorrt_llm.scaffolding.contrib.Coder import create_swebench_coder_scaffolding_llm
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_SWEBENCH_OUTPUT_DIR = Path("./swebench_output")
+
+
+def build_prompt(instance: dict[str, Any]) -> str:
+    """Build the SWE-bench prompt for one instance."""
+    parts = [
+        "<pr_description>",
+        instance["problem_statement"],
+        "</pr_description>",
+    ]
+    hints = instance.get("hints_text", "")
+    if hints and hints.strip():
+        parts.extend(["", "<hints>", hints.strip(), "</hints>"])
+    return "\n".join(parts)
+
+
+def update_preds(
+    preds_path: Path,
+    instance_id: str,
+    model_name: str,
+    patch: str,
+    summary: str | None = None,
+) -> None:
+    """Update the SWE-bench predictions file."""
+    data: dict[str, dict[str, str]] = {}
+    if preds_path.exists():
+        data = json.loads(preds_path.read_text())
+    record = {
+        "model_name_or_path": model_name,
+        "instance_id": instance_id,
+        "model_patch": patch,
+    }
+    if summary is not None:
+        record["summary"] = summary
+    data[instance_id] = record
+    preds_path.write_text(json.dumps(data, indent=2))
+
+
+def save_trajectory(
+    output_dir: Path,
+    instance_id: str,
+    prompt: str,
+    output_text: str,
+    elapsed_s: float,
+) -> None:
+    """Persist the trajectory for one SWE-bench instance."""
+    instance_dir = output_dir / instance_id
+    instance_dir.mkdir(parents=True, exist_ok=True)
+    trajectory = {
+        "instance_id": instance_id,
+        "prompt": prompt,
+        "output": output_text,
+        "elapsed_seconds": elapsed_s,
+    }
+    (instance_dir / f"{instance_id}.traj.json").write_text(json.dumps(trajectory, indent=2))
+
+
+def safe_output_component(value: str) -> str:
+    """Return a filesystem-safe label for SWE-bench run directory names."""
+    label = Path(value).stem if Path(value).suffix else value
+    return re.sub(r"[^A-Za-z0-9_.-]+", "_", label).strip("_") or "unknown"
+
+
+def default_swebench_output_dir(dataset: str, split: str, model: str) -> Path:
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    run_name = "-".join(
+        [
+            safe_output_component(dataset),
+            safe_output_component(split),
+            safe_output_component(model),
+            timestamp,
+        ]
+    )
+    return DEFAULT_SWEBENCH_OUTPUT_DIR / run_name
+
+
+def _duration_ms(value: Any) -> float:
+    if isinstance(value, (int, float)):
+        return float(value)
+    return 0.0
+
+
+def _tool_call_time_summary(trace_path: Path) -> dict[str, float | int]:
+    data = json.loads(trace_path.read_text(encoding="utf-8"))
+    events = data.get("events", [])
+    if not isinstance(events, list):
+        raise ValueError(f"{trace_path} must contain an events list.")
+
+    tool_call_count = 0
+    llm_turn_count = 0
+    tool_call_duration_ms = 0.0
+    llm_duration_ms = 0.0
+    for event in events:
+        if not isinstance(event, dict):
+            continue
+        if event.get("event_type") == "tool_call":
+            tool_call_count += 1
+            tool_call_duration_ms += _duration_ms(event.get("duration_ms"))
+        elif event.get("event_type") == "message" and event.get("role") == "assistant":
+            duration_ms = _duration_ms(event.get("llm_duration_ms"))
+            if duration_ms > 0:
+                llm_turn_count += 1
+                llm_duration_ms += duration_ms
+
+    recorded_duration_ms = tool_call_duration_ms + llm_duration_ms
+    tool_call_time_ratio = (
+        tool_call_duration_ms / recorded_duration_ms if recorded_duration_ms > 0 else 0.0
+    )
+    return {
+        "event_count": len(events),
+        "tool_call_count": tool_call_count,
+        "llm_turn_count": llm_turn_count,
+        "tool_call_duration_ms": tool_call_duration_ms,
+        "llm_duration_ms": llm_duration_ms,
+        "recorded_duration_ms": recorded_duration_ms,
+        "tool_call_time_ratio": tool_call_time_ratio,
+        "tool_call_time_percent": tool_call_time_ratio * 100,
+    }
+
+
+def write_tool_call_time_summary(
+    trace_path: Path,
+    output_path: Path,
+    elapsed_s: float,
+) -> None:
+    """Write per-trace tool-call time share computed from the full trace."""
+    summary = _tool_call_time_summary(trace_path)
+    elapsed_ms = elapsed_s * 1000
+    elapsed_ratio = summary["tool_call_duration_ms"] / elapsed_ms if elapsed_ms > 0 else 0.0
+    lines = [
+        f"trace_path: {trace_path}",
+        f"event_count: {summary['event_count']}",
+        f"tool_call_count: {summary['tool_call_count']}",
+        f"llm_turn_count: {summary['llm_turn_count']}",
+        f"tool_call_duration_ms: {summary['tool_call_duration_ms']:.3f}",
+        f"llm_duration_ms: {summary['llm_duration_ms']:.3f}",
+        f"recorded_duration_ms: {summary['recorded_duration_ms']:.3f}",
+        f"tool_call_time_ratio: {summary['tool_call_time_ratio']:.6f}",
+        f"tool_call_time_percent: {summary['tool_call_time_percent']:.2f}%",
+        f"elapsed_seconds: {elapsed_s:.3f}",
+        f"tool_call_elapsed_time_ratio: {elapsed_ratio:.6f}",
+        f"tool_call_elapsed_time_percent: {elapsed_ratio * 100:.2f}%",
+        "",
+    ]
+    output_path.write_text("\n".join(lines), encoding="utf-8")
+
+
+def _split_instance_ids(instance_ids: list[str] | None) -> list[str]:
+    """Parse instance IDs from space-separated and comma-separated CLI values."""
+    if not instance_ids:
+        return []
+
+    parsed_ids: list[str] = []
+    for value in instance_ids:
+        parsed_ids.extend(
+            instance_id.strip() for instance_id in value.split(",") if instance_id.strip()
+        )
+    return parsed_ids
+
+
+def _load_instance_ids_file(instance_ids_file: str | None) -> list[str]:
+    """Load instance IDs from a text file, ignoring blank lines and comments."""
+    if not instance_ids_file:
+        return []
+
+    path = Path(instance_ids_file)
+    instance_ids: list[str] = []
+    for line in path.read_text().splitlines():
+        value = line.split("#", maxsplit=1)[0].strip()
+        if value:
+            instance_ids.append(value)
+    return instance_ids
+
+
+def resolve_instance_ids(args: argparse.Namespace) -> list[str]:
+    """Resolve the requested SWE-bench instance IDs from CLI arguments."""
+    instance_ids = _split_instance_ids(args.instance_ids)
+    instance_ids.extend(_load_instance_ids_file(args.instance_ids_file))
+    return list(dict.fromkeys(instance_ids))
+
+
+def write_selected_instances(
+    dataset: str,
+    split: str,
+    instance_ids: list[str],
+    output_path: Path,
+) -> Path:
+    """Write a filtered local JSON dataset for the selected SWE-bench instances."""
+    instances = load_instances(dataset, split)
+    requested_ids = set(instance_ids)
+    selected_instances = [
+        instance for instance in instances if instance.get("instance_id") in requested_ids
+    ]
+    selected_ids = {instance["instance_id"] for instance in selected_instances}
+    missing_ids = sorted(requested_ids - selected_ids)
+    if missing_ids:
+        raise ValueError(
+            f"Requested instance IDs were not found in dataset={dataset!r} "
+            f"split={split!r}: "
+            + ", ".join(missing_ids)
+            + ". Check that --dataset and --split match the selected IDs."
+        )
+
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(json.dumps(selected_instances, indent=2))
+    return output_path
+
+
+def parse_arguments():
+    parser = argparse.ArgumentParser(
+        description="Run SWE-bench evaluation using the Coder agent with Apiary sandboxes."
+    )
+
+    parser.add_argument("--openai_api_key", default="tensorrt_llm")
+    parser.add_argument("--base_url", default="http://localhost:8000/v1")
+    parser.add_argument("--model", default="Qwen3/Qwen3-30B-A3B")
+    parser.add_argument("--max_tokens", type=int, default=16384)
+    parser.add_argument("--max_iterations", type=int, default=100)
+
+    parser.add_argument("--mcp_url", default="http://0.0.0.0:8086/sse")
+    parser.add_argument("--max_mcp_connections", type=int, default=200)
+
+    parser.add_argument(
+        "--apiary_url",
+        default=os.getenv("APIARY_URL", "http://127.0.0.1:8080"),
+        help="Apiary daemon URL for runtime image registration",
+    )
+    parser.add_argument(
+        "--apiary_token",
+        default=os.getenv("APIARY_API_TOKEN"),
+        help="Bearer token for the Apiary daemon",
+    )
+    parser.add_argument(
+        "--apiary_load_timeout",
+        type=float,
+        default=None,
+        help="Maximum seconds to wait for Apiary image registration (default: no timeout)",
+    )
+
+    parser.add_argument(
+        "--dataset",
+        required=True,
+        help="Local JSON/JSONL path or HuggingFace dataset name/alias",
+    )
+    parser.add_argument(
+        "--split",
+        default="test",
+        help="HuggingFace split to load when --dataset is not a local file",
+    )
+    parser.add_argument(
+        "--instance_ids",
+        nargs="+",
+        default=None,
+        help=(
+            "Optional SWE-bench instance IDs to run. Accepts space-separated "
+            "values, comma-separated values, or both."
+        ),
+    )
+    parser.add_argument(
+        "--instance_ids_file",
+        default=None,
+        help=(
+            "Optional text file containing SWE-bench instance IDs to run, "
+            "one per line. Blank lines and comments are ignored."
+        ),
+    )
+    parser.add_argument(
+        "--selected_dataset_path",
+        default=None,
+        help=(
+            "Path to write the filtered JSON dataset when instance IDs are "
+            "specified. Defaults to <output_dir>/selected_instances.json."
+        ),
+    )
+
+    parser.add_argument(
+        "--output_dir",
+        default=None,
+        help=(
+            "Directory for preds.json, selected_instances.json, trajectories, and traces. "
+            "Default: ./swebench_output/<dataset>-<split>-<model>-<time>."
+        ),
+    )
+    parser.add_argument("--max_parallel_requests", type=int, default=16)
+
+    parser.add_argument("--enable_statistics", action="store_true")
+    parser.add_argument("--enable_tracing", action="store_true")
+
+    return parser.parse_args()
+
+
+def _log_image_progress(status: ImageJobStatus) -> None:
+    """Progress callback for the AsyncApiary load loop."""
+    counts = {
+        "queued": 0,
+        "pulling": 0,
+        "extracting": 0,
+        "done": 0,
+        "alreadypresent": 0,
+        "failed": 0,
+    }
+    for prog in status.per_image.values():
+        counts[prog.state] = counts.get(prog.state, 0) + 1
+    total = sum(counts.values())
+    finished = counts["done"] + counts["alreadypresent"] + counts["failed"]
+    logger.info(
+        "Apiary image-load job=%s state=%s progress=%d/%d "
+        "(done=%d, present=%d, pulling=%d, extracting=%d, queued=%d, failed=%d)",
+        status.job_id[:8],
+        status.state,
+        finished,
+        total,
+        counts["done"],
+        counts["alreadypresent"],
+        counts["pulling"],
+        counts["extracting"],
+        counts["queued"],
+        counts["failed"],
+    )
+
+
+async def register_swebench_images(
+    images: list[str],
+    apiary_url: str,
+    apiary_token: str | None,
+    load_timeout: float | None,
+) -> dict[str, Any]:
+    """Register the SWE-bench image set with the Apiary daemon and report status.
+
+    Apiary returns 404 for any session targeting an unregistered image. This
+    helper waits for the daemon to be healthy, submits the image set via
+    :class:`AsyncApiary`, polls the load job to completion (logging per-image
+    progress), and surfaces per-image failures so callers can decide how to
+    react. Returns the daemon's :code:`/api/v1/status` snapshot for logging.
+    """
+    apiary = AsyncApiary(
+        apiary_url=apiary_url,
+        apiary_token=apiary_token,
+        images=images,
+        load_timeout=load_timeout,
+        on_progress=_log_image_progress,
+    )
+    try:
+        if not await apiary.health_check(retries=30, interval=1.0):
+            raise RuntimeError(
+                f"Apiary daemon at {apiary_url} is not reachable. "
+                "Start it with `apiary init && apiary daemon --bind ...`."
+            )
+        status = await apiary.load()
+        if status is None:
+            raise RuntimeError("register_swebench_images: empty image set")
+        if status.state == "failed":
+            raise RuntimeError(
+                f"Apiary failed to load any of the {len(images)} SWE-bench images; "
+                f"failures: {status.failed_images}"
+            )
+        if status.failed:
+            for entry in status.failed_images:
+                logger.error(
+                    "Apiary image %s failed: %s",
+                    entry.get("name"),
+                    entry.get("reason", "unknown"),
+                )
+            logger.warning(
+                "%d of %d SWE-bench images failed to load; instances using those "
+                "images will fail at session-creation time",
+                len(status.failed),
+                len(images),
+            )
+        logger.info(
+            "Apiary registered %d SWE-bench images (succeeded=%d, failed=%d)",
+            len(images),
+            len(status.succeeded),
+            len(status.failed),
+        )
+        return await apiary.status()
+    finally:
+        await apiary.close()
+
+
+async def main():
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )
+    args = parse_arguments()
+    output_dir = (
+        Path(args.output_dir)
+        if args.output_dir is not None
+        else default_swebench_output_dir(args.dataset, args.split, args.model)
+    )
+    output_dir.mkdir(parents=True, exist_ok=True)
+    preds_path = output_dir / "preds.json"
+
+    dataset = args.dataset
+    instance_ids = resolve_instance_ids(args)
+    if instance_ids:
+        selected_dataset_path = Path(
+            args.selected_dataset_path or output_dir / "selected_instances.json"
+        )
+        logger.info(
+            "Selecting %d instances from %s and writing %s ...",
+            len(instance_ids),
+            args.dataset,
+            selected_dataset_path,
+        )
+        dataset = str(
+            write_selected_instances(
+                args.dataset,
+                args.split,
+                instance_ids,
+                selected_dataset_path,
+            )
+        )
+
+    logger.info("[Phase 1] Loading dataset ...")
+    instances = load_instances(dataset, args.split)
+    if not instances:
+        logger.info("No instances to process.")
+        return
+
+    unique_images = sorted({get_docker_image(instance) for instance in instances})
+    logger.info(
+        "%d instances, %d unique Docker images",
+        len(instances),
+        len(unique_images),
+    )
+
+    logger.info("[Phase 1] Registering %d images with Apiary ...", len(unique_images))
+    status = await register_swebench_images(
+        unique_images,
+        args.apiary_url,
+        args.apiary_token,
+        args.apiary_load_timeout,
+    )
+    logger.info(
+        "Apiary ready: total=%s busy=%s error=%s max_sandboxes=%s registered_images=%s",
+        status.get("total", "n/a"),
+        status.get("busy", "n/a"),
+        status.get("error", "n/a"),
+        status.get("max_sandboxes", "n/a"),
+        status.get("registered_images", "n/a"),
+    )
+
+    logger.info("[Phase 2] Running agents ...")
+    client = AsyncOpenAI(api_key=args.openai_api_key, base_url=args.base_url)
+    generation_worker = TRTOpenaiWorker(client, args.model)
+    mcp_worker = ApiaryMCPWorker(
+        args.mcp_url,
+        max_connections=args.max_mcp_connections,
+    )
+
+    llm = create_swebench_coder_scaffolding_llm(
+        generation_worker,
+        mcp_worker,
+        max_tokens=args.max_tokens,
+        max_iterations=args.max_iterations,
+        max_parallel_requests=args.max_parallel_requests,
+        enable_statistics=args.enable_statistics,
+        enable_tracing=args.enable_tracing,
+    )
+
+    pending: list[tuple[dict[str, Any], str, Any, float]] = []
+    for instance in instances:
+        prompt = build_prompt(instance)
+        result = llm.generate_async(prompt)
+        mcp_worker.set_scope_params(
+            result.id,
+            image=get_docker_image(instance),
+        )
+        pending.append((instance, prompt, result, time.monotonic()))
+
+    logger.info("Dispatched %d instances, awaiting results ...", len(pending))
+
+    completed = 0
+    errored = 0
+    for instance, prompt, result, start_time in pending:
+        instance_id = instance["instance_id"]
+        try:
+            output = await result.aresult()
+            elapsed = time.monotonic() - start_time
+            text = output.outputs[0].text or ""
+            metadata = output.outputs[0].metadata or {}
+            model_patch = metadata.get("swebench_model_patch", text)
+            summary = metadata.get("swebench_summary")
+            if not isinstance(model_patch, str):
+                model_patch = str(model_patch)
+            if summary is not None and not isinstance(summary, str):
+                summary = str(summary)
+
+            save_trajectory(output_dir, instance_id, prompt, text, elapsed)
+            update_preds(preds_path, instance_id, args.model, model_patch, summary)
+
+            if args.enable_tracing and result.task_collections:
+                tracer = result.task_collections.get("execution_tracer")
+                if tracer:
+                    trace = tracer.export_trace()
+                    instance_dir = output_dir / instance_id
+                    trace_path = instance_dir / f"{instance_id}.trace.json"
+                    full_trace_path = instance_dir / f"{instance_id}.full.trace.json"
+                    tool_call_time_path = instance_dir / "tool_call_time_summary.txt"
+                    trace.save(str(trace_path))
+                    trace.save(str(full_trace_path), full=True)
+                    write_tool_call_time_summary(
+                        full_trace_path,
+                        tool_call_time_path,
+                        elapsed,
+                    )
+                    logger.info("Execution trace saved to %s", trace_path)
+                    logger.info("Full execution trace saved to %s", full_trace_path)
+                    logger.info("Tool-call time summary saved to %s", tool_call_time_path)
+
+            completed += 1
+            logger.info(
+                "[%d/%d] %s completed (%.1fs)",
+                completed + errored,
+                len(pending),
+                instance_id,
+                elapsed,
+            )
+        except Exception:
+            errored += 1
+            logger.error("Instance %s failed", instance_id, exc_info=True)
+
+    logger.info(
+        "Completed: %d, Errors: %d, Total: %d",
+        completed,
+        errored,
+        len(pending),
+    )
+    logger.info("Predictions: %s", preds_path)
+
+    await mcp_worker.async_shutdown()
+    llm.shutdown()
+    generation_worker.shutdown()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/scaffolding/contrib/iter_research/README.md b/examples/scaffolding/contrib/iter_research/README.md
new file mode 100644
index 000000000000..4a8a6a2d2eb5
--- /dev/null
+++ b/examples/scaffolding/contrib/iter_research/README.md
@@ -0,0 +1,68 @@
+# IterResearch (scaffolding example)
+
+Multi-tool research agent using TensorRT-LLM scaffolding: Tavily search, Google Scholar, webpage fetch, and an optional Python sandbox via `coder_mcp`.
+
+Configuration (API keys, MCP host/ports, `base_url`, model name, turn/token limits) uses the shared example config `examples/scaffolding/contrib/open_deep_research/config.example.yaml`. IterResearch, Tree-of-Thought Research, and Open Deep Research all share the same layout, so there is no per-agent config file — copy the example to your own `config.yaml` and fill in the keys.
+
+```bash
+cd examples/scaffolding/mcp/tavily_search && uv run tavily_search.py \
+    --config examples/scaffolding/contrib/open_deep_research/config.example.yaml
+```
+```bash
+cd examples/scaffolding/mcp/google_scholar && uv run google_scholar.py \
+    --config examples/scaffolding/contrib/open_deep_research/config.example.yaml
+```
+```bash
+cd examples/scaffolding/mcp/fetch_webpage && uv run fetch_webpage.py \
+    --config examples/scaffolding/contrib/open_deep_research/config.example.yaml
+```
+```bash
+python examples/scaffolding/mcp/coder/coder_mcp.py \
+    --apiary-url http://172.17.0.1:8080 \
+    --default-image python:3.12-slim \
+    --port 8086
+```
+
+## Prerequisites
+
+1. Serve a compatible chat model (for example with `trtllm-serve`) so `base_url` in `config.yaml` points at a running OpenAI-compatible API.
+2. Start the Python sandbox MCP if you need code execution: run `coder_mcp.py` (Apiary-backed), then the MCP servers—see comments in `config.yaml` for host/port wiring.
+3. Start the MCP tools you need (same `config.yaml` passed to each server, for example `uv run … --config …/config.yaml`).
+4. Fill in search/scraper keys in `config.yaml` where required.
+
+## Single question
+
+```bash
+python examples/scaffolding/contrib/iter_research/run_iter_research.py \
+  --config examples/scaffolding/contrib/open_deep_research/config.example.yaml \
+  --enable_tracing --enable_statistics
+```
+
+Use `--question "…"` to override the default prompt. Outputs and traces depend on the flags you pass.
+
+## Tracing (`--enable_tracing`)
+
+`--enable_tracing` turns on execution trace capture for one IterResearch run.
+
+### Output directory behavior
+
+- If `--trace_output_dir` is set, traces are written there.
+- Otherwise, the script creates a timestamped folder: `iter_research_trace_<YYYYMMDD_HHMMSS>`.
+- The script prints the final trace output directory at runtime.
+
+### Files written when tracing is enabled
+
+- `iter_research.trace.json`: compact trace for replay-oriented workflows.
+- `iter_research.full.trace.json`: full trace with richer event payloads.
+
+### Optional explicit output directory
+
+```bash
+python examples/scaffolding/contrib/iter_research/run_iter_research.py \
+  --config examples/scaffolding/contrib/open_deep_research/config.example.yaml \
+  --enable_tracing \
+  --trace_output_dir ./iter_research_trace_manual
+```
+
+The generated `.trace.json` files can be consumed by replay scripts under
+`examples/scaffolding/trace_replay`.
diff --git a/examples/scaffolding/contrib/iter_research/run_iter_research.py b/examples/scaffolding/contrib/iter_research/run_iter_research.py
new file mode 100644
index 000000000000..a02844e93137
--- /dev/null
+++ b/examples/scaffolding/contrib/iter_research/run_iter_research.py
@@ -0,0 +1,194 @@
+r"""IterResearch runner (TensorRT-LLM scaffolding).
+
+Start Apiary, then ``apiary_python_gateway.py``, then MCP servers and LLM, then::
+
+    python examples/scaffolding/contrib/iter_research/run_iter_research.py \\
+        --config examples/scaffolding/contrib/open_deep_research/config.example.yaml --enable_tracing
+"""
+
+import argparse
+import asyncio
+import io
+from contextlib import redirect_stdout
+from datetime import datetime
+from pathlib import Path
+
+import yaml
+from openai import AsyncOpenAI
+
+from tensorrt_llm.scaffolding import MCPWorker, TaskMetricsCollector, TRTOpenaiWorker
+from tensorrt_llm.scaffolding.contrib.iter_research import create_iter_research_scaffolding_llm
+
+
+def parse_arguments():
+    parser = argparse.ArgumentParser(description="IterResearch with TensorRT-LLM scaffolding")
+    parser.add_argument("--config", type=str, default=None, help="Path to config.yaml")
+    parser.add_argument("--openai_api_key", type=str, default=None)
+    parser.add_argument("--base_url", type=str, default=None)
+    parser.add_argument("--model", type=str, default=None)
+    parser.add_argument("--max_turn", type=int, default=None)
+    parser.add_argument("--max_tokens", type=int, default=None)
+    parser.add_argument("--max_tavily_search_chars", type=int, default=None)
+    parser.add_argument("--question", type=str, default=None, help="Research question to ask")
+    parser.add_argument(
+        "--enable_statistics",
+        action="store_true",
+        help="Print live task metrics and save the final summary as text. Does not write metrics JSON.",
+    )
+    parser.add_argument("--enable_tracing", action="store_true")
+    parser.add_argument(
+        "--trace_output_dir",
+        type=str,
+        default=None,
+        help="Directory for trace outputs when --enable_tracing is set",
+    )
+    return parser.parse_args()
+
+
+def _load_config(config_path: str | None) -> dict:
+    if config_path and Path(config_path).is_file():
+        with open(config_path) as f:
+            return yaml.safe_load(f) or {}
+    return {}
+
+
+_MCP_SERVICE_ORDER = (
+    # ("google_search", 8083),
+    ("tavily_search", 8087),
+    # ("google_scholar", 8084),
+    ("fetch_webpage", 8085),
+    ("python_interpreter", 8086),
+)
+
+
+def _mcp_sse_urls(cfg: dict) -> list[str]:
+    tools = cfg.get("mcp_tools") or {}
+    ch = str(cfg.get("mcp_client_host") or "127.0.0.1")
+    out: list[str] = []
+    for name, default_port in _MCP_SERVICE_ORDER:
+        t = tools.get(name) or {}
+        out.append(f"http://{t.get('client_host') or ch}:{int(t.get('port', default_port))}/sse")
+    return out
+
+
+def _dump_task_metrics_summary(output_dir: Path) -> None:
+    buf = io.StringIO()
+    with redirect_stdout(buf):
+        TaskMetricsCollector.print_summary()
+    summary = buf.getvalue()
+    print(summary, end="")
+
+    summary_path = output_dir / "iter_research.metrics.txt"
+    summary_path.write_text(summary, encoding="utf-8")
+    print(f"Task metrics summary saved to {summary_path}")
+
+
+async def main():
+    args = parse_arguments()
+    cfg = _load_config(args.config)
+
+    openai_api_key = args.openai_api_key or cfg.get("openai_api_key", "tensorrt_llm")
+    base_url = args.base_url or cfg.get("base_url", "http://localhost:8000/v1")
+    model = args.model or cfg.get("model", "Qwen/Qwen2.5-72B-Instruct")
+    mcp_urls = _mcp_sse_urls(cfg)
+    max_turn = args.max_turn or cfg.get("max_turn", 25)
+    max_tokens = args.max_tokens or cfg.get("max_tokens", 16384)
+    max_tavily_search_chars = (
+        args.max_tavily_search_chars
+        if args.max_tavily_search_chars is not None
+        else int(cfg.get("max_tavily_search_chars", 6000))
+    )
+    trace_output_dir: Path | None = None
+    if args.enable_tracing or args.enable_statistics:
+        trace_output_dir_str = args.trace_output_dir or cfg.get("trace_output_dir")
+        if trace_output_dir_str:
+            trace_output_dir = Path(trace_output_dir_str)
+        else:
+            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+            trace_output_dir = Path(f"iter_research_trace_{timestamp}")
+        trace_output_dir.mkdir(parents=True, exist_ok=True)
+
+    client = AsyncOpenAI(api_key=openai_api_key, base_url=base_url)
+    generation_worker = TRTOpenaiWorker(client, model)
+
+    print(f"MCP SSE URLs ({len(mcp_urls)}): {mcp_urls}")
+    if args.enable_statistics:
+        TaskMetricsCollector.reset()
+        print(
+            "Statistics enabled: "
+            f"model={model}, base_url={base_url}, max_turn={max_turn}, "
+            f"max_tokens={max_tokens}, max_tavily_search_chars={max_tavily_search_chars}"
+        )
+    mcp_worker = MCPWorker.init_with_urls(mcp_urls)
+    await mcp_worker.init_in_asyncio_event_loop()
+
+    llm = create_iter_research_scaffolding_llm(
+        generation_worker,
+        mcp_worker,
+        max_tokens=max_tokens,
+        max_turn=max_turn,
+        max_tavily_search_chars=max_tavily_search_chars,
+        enable_statistics=args.enable_statistics,
+        enable_tracing=args.enable_tracing,
+    )
+
+    # question = args.question or (
+    #     "What are the latest advances in large language model inference "
+    #     "optimization? Compare the approaches of vLLM, TensorRT-LLM, and "
+    #     "SGLang in terms of performance, features, and architecture.")
+    question = args.question or (
+        "Fetch the live HTML/markdown from https://www.timeanddate.com/worldclock/ "
+        "and tell me the exact current time shown for New York City on that page right now."
+    )
+    # question = args.question or (
+    #     "In the sandbox, run Python to simulate 200,000 rolls of two fair six-sided dice, "
+    #     "count how often the sum is 7, and report the empirical probability"
+    #     " and the code’s stdout (no hand calculation).")
+    # question = args.question or (
+    #     "The player, born between 1981 and 1984, started their career between 1999 and "
+    #     "2002. Between 2006 and 2009, they joined a club formed between 1930 and 1933. "
+    #     "The club’s team reached Wembley for the first time for the FA Cup final "
+    #     "between 1971 and 1974. The player scored two goals that sent their team to the "
+    #     "cup final between 2009 and 2012 and retired in August between 2013 and 2016. "
+    #     "What is the player’s name?"
+    # )
+
+    print(f"Question: {question}")
+    print(f"Max turns: {max_turn}")
+    if trace_output_dir is not None:
+        print(f"Trace output directory: {trace_output_dir}")
+    print("Starting IterResearch...")
+
+    try:
+        future = llm.generate_async(question)
+        result = await future.aresult()
+
+        assert result.outputs[0].text is not None
+        print("\n" + "=" * 80)
+        print("FINAL ANSWER:")
+        print("=" * 80)
+        print(result.outputs[0].text)
+
+        if args.enable_tracing and result.task_collections:
+            tracer = result.task_collections.get("execution_tracer")
+            if tracer:
+                trace = tracer.export_trace()
+                assert trace_output_dir is not None
+                trace_path = trace_output_dir / "iter_research.trace.json"
+                full_trace_path = trace_output_dir / "iter_research.full.trace.json"
+                trace.save(str(trace_path))
+                trace.save(str(full_trace_path), full=True)
+                print(f"Execution trace saved to {trace_path}")
+                print(f"Full execution trace saved to {full_trace_path}")
+    finally:
+        if args.enable_statistics:
+            assert trace_output_dir is not None
+            _dump_task_metrics_summary(trace_output_dir)
+
+        llm.shutdown()
+        generation_worker.shutdown()
+        mcp_worker.shutdown()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/scaffolding/contrib/mcp/README.md b/examples/scaffolding/contrib/mcp/README.md
deleted file mode 100644
index ca5fac049961..000000000000
--- a/examples/scaffolding/contrib/mcp/README.md
+++ /dev/null
@@ -1,50 +0,0 @@
-# MCP USAGE
-
-## Step1: Run Servers
-
-### Terminal1:
-
-`cd weather`
-
-`pip install uv`
-
-`uv add "mcp[cli]" httpx openai`
-
-`uv pip install httpx mcp`
-`uv init --no-workspace`
-`uv run weather.py`
-
-
-
-### Terminal2:
-
-`cd e2b`
-
-`pip install uv`
-
-`uv add "mcp[cli]" httpx openai`
-
-`uv pip install e2b_code_interpreter mcp`
-`uv init --no-workspace`
-`uv run e2bserver.py`
-
-
-
-### Terminal3:
-
-`cd websearch`
-
-`pip install uv`
-
-`uv add "mcp[cli]" httpx openai`
-`uv pip install brave-search mcp starlette uvicorn`
-`uv init --no-workspace`
-`uv run websearch.py`
-
-
-
-
-
-## Step2: Run Test
-
-`python3 mcptest.py --API_KEY YOUR_API_KEY`
diff --git a/examples/scaffolding/contrib/mcp/weather/uv.lock b/examples/scaffolding/contrib/mcp/weather/uv.lock
deleted file mode 100644
index a6c1670c970b..000000000000
--- a/examples/scaffolding/contrib/mcp/weather/uv.lock
+++ /dev/null
@@ -1,8 +0,0 @@
-version = 1
-revision = 3
-requires-python = ">=3.12"
-
-[[package]]
-name = "mcp"
-version = "0.1.0"
-source = { virtual = "." }
diff --git a/examples/scaffolding/contrib/mcp/websearch/.env b/examples/scaffolding/contrib/mcp/websearch/.env
deleted file mode 100644
index e32a5841387b..000000000000
--- a/examples/scaffolding/contrib/mcp/websearch/.env
+++ /dev/null
@@ -1 +0,0 @@
-BRAVE_API_KEY=$YOUR_API_KEY
diff --git a/examples/scaffolding/contrib/mcp/websearch/README.md b/examples/scaffolding/contrib/mcp/websearch/README.md
deleted file mode 100644
index e69de29bb2d1..000000000000
diff --git a/examples/scaffolding/contrib/mcp/websearch/main.py b/examples/scaffolding/contrib/mcp/websearch/main.py
deleted file mode 100644
index 9d579b76c3f0..000000000000
--- a/examples/scaffolding/contrib/mcp/websearch/main.py
+++ /dev/null
@@ -1,6 +0,0 @@
-def main():
-    print("Hello from websearch!")
-
-
-if __name__ == "__main__":
-    main()
diff --git a/examples/scaffolding/contrib/mcp/websearch/pyproject.toml b/examples/scaffolding/contrib/mcp/websearch/pyproject.toml
deleted file mode 100644
index 9a228c47df88..000000000000
--- a/examples/scaffolding/contrib/mcp/websearch/pyproject.toml
+++ /dev/null
@@ -1,11 +0,0 @@
-[project]
-name = "websearch"
-version = "0.1.0"
-description = "Add your description here"
-readme = "README.md"
-requires-python = ">=3.12"
-dependencies = [
-    "httpx>=0.28.1",
-    "mcp[cli]>=1.9.0",
-    "openai>=1.79.0",
-]
diff --git a/examples/scaffolding/contrib/mcp/websearch/websearch.py b/examples/scaffolding/contrib/mcp/websearch/websearch.py
deleted file mode 100644
index 1df22174555c..000000000000
--- a/examples/scaffolding/contrib/mcp/websearch/websearch.py
+++ /dev/null
@@ -1,76 +0,0 @@
-import os
-
-import uvicorn
-from brave import Brave
-from dotenv import load_dotenv
-from mcp.server import Server
-from mcp.server.fastmcp import FastMCP
-from mcp.server.sse import SseServerTransport
-from starlette.applications import Starlette
-from starlette.requests import Request
-from starlette.routing import Mount, Route
-
-# Initialize FastMCP server for Weather tools (SSE)
-mcp = FastMCP("websearch")
-
-# Load environment variables
-load_dotenv()
-
-
-@mcp.tool()
-async def websearch(query: str) -> str:
-    """Web search, fetch information from the internet
-    Args:
-        query:  string of what you want to search
-    """
-    BRAVE_API_KEY = os.getenv("BRAVE_API_KEY")
-    brave = Brave(BRAVE_API_KEY)
-    print(f"brave apikey {BRAVE_API_KEY }")
-    search_results = brave.search(q=query, raw=True)
-    return f"{search_results}"
-
-
-def create_starlette_app(mcp_server: Server,
-                         *,
-                         debug: bool = False) -> Starlette:
-    """Create a Starlette application that can server the provided mcp server with SSE."""
-    sse = SseServerTransport("/messages/")
-
-    async def handle_sse(request: Request) -> None:
-        async with sse.connect_sse(
-                request.scope,
-                request.receive,
-                request._send,  # noqa: SLF001
-        ) as (read_stream, write_stream):
-            await mcp_server.run(
-                read_stream,
-                write_stream,
-                mcp_server.create_initialization_options(),
-            )
-
-    return Starlette(
-        debug=debug,
-        routes=[
-            Route("/sse", endpoint=handle_sse),
-            Mount("/messages/", app=sse.handle_post_message),
-        ],
-    )
-
-
-if __name__ == "__main__":
-    mcp_server = mcp._mcp_server  # noqa: WPS437
-
-    import argparse
-
-    parser = argparse.ArgumentParser(description='Run MCP SSE-based server')
-    parser.add_argument('--host', default='0.0.0.0', help='Host to bind to')
-    parser.add_argument('--port',
-                        type=int,
-                        default=8082,
-                        help='Port to listen on')
-    args = parser.parse_args()
-
-    # Bind SSE request handling to MCP server
-    starlette_app = create_starlette_app(mcp_server, debug=True)
-
-    uvicorn.run(starlette_app, host=args.host, port=args.port)
diff --git a/examples/scaffolding/contrib/open_deep_research/README.md b/examples/scaffolding/contrib/open_deep_research/README.md
new file mode 100644
index 000000000000..301def964690
--- /dev/null
+++ b/examples/scaffolding/contrib/open_deep_research/README.md
@@ -0,0 +1,75 @@
+# Open Deep Research (scaffolding example)
+
+Research agent built on TensorRT-LLM scaffolding with the same MCP stack as IterResearch (Tavily, Google Scholar, webpage fetch, optional Python sandbox via `coder_mcp`). Batch runs use JSONL benchmarks under `search_datasets/` (`browsecomp`, `hle`).
+
+Configuration and ports live in `config.example.yaml` — the shared example config used by all three research-agent examples (IterResearch, Tree-of-Thought Research, Open Deep Research), since they use the same layout. Copy it to your own `config.yaml` and fill in the keys, or pass `config.example.yaml` directly to `--config`.
+
+## Prerequisites
+
+1. Serve a chat model at an OpenAI-compatible `base_url` (for example `trtllm-serve`).
+2. If you need code execution, start `coder_mcp.py` (Apiary-backed), then the MCP servers (see comments in `config.yaml`).
+3. Start the MCP tools you need, passing the **same** `config.yaml` to each server, for example `uv run … --config …/config.yaml`.
+   ```bash
+   cd examples/scaffolding/mcp/tavily_search && uv run tavily_search.py \
+       --config examples/scaffolding/contrib/open_deep_research/config.example.yaml
+    ```
+    ```bash
+   cd examples/scaffolding/mcp/google_scholar && uv run google_scholar.py \
+       --config examples/scaffolding/contrib/open_deep_research/config.example.yaml
+    ```
+    ```bash
+   cd examples/scaffolding/mcp/fetch_webpage && uv run fetch_webpage.py \
+       --config examples/scaffolding/contrib/open_deep_research/config.example.yaml
+    ```
+    ```bash
+  python examples/scaffolding/mcp/coder/coder_mcp.py \
+      --apiary-url http://172.17.0.1:8080 \
+      --default-image python:3.12-slim \
+      --port 8086
+    ```
+
+4. Fill in API keys in `config.yaml` (Tavily, Jina/Scraper for fetch, Google keys for scholar, etc.).
+
+## Single prompt
+
+```bash
+python examples/scaffolding/contrib/open_deep_research/run_open_deep_research.py \
+  --config examples/scaffolding/contrib/open_deep_research/config.example.yaml \
+  --base_url http://localhost:8000/v1 \
+  --model Qwen3/Qwen3-30B-A3B \
+  --enable_tracing
+```
+
+Override `--prompt` for your own question. Add `--enable_tracing` or `--enable_query_collector` as needed. CLI flags override values from `--config` when both are set.
+
+## Tracing (`--enable_tracing`)
+
+`--enable_tracing` enables execution trace capture for a single Open Deep Research run.
+
+### Output directory behavior
+
+- If `--trace_output_dir` is provided, outputs are written to that directory.
+- Otherwise, the script creates a timestamped directory:
+  `open_deep_research_trace_<YYYYMMDD_HHMMSS>`.
+- The script prints the chosen trace output directory during execution.
+
+### Files written when tracing is enabled
+
+- `open_deep_research.trace.json`: compact trace for replay and analysis.
+- `open_deep_research.full.trace.json`: full trace with complete event payloads.
+
+### Example with explicit trace directory
+
+```bash
+python examples/scaffolding/contrib/open_deep_research/run_open_deep_research.py \
+  --config examples/scaffolding/contrib/open_deep_research/config.example.yaml \
+  --base_url http://localhost:8000/v1 \
+  --model Qwen3/Qwen3-235B-A22B \
+  --enable_tracing \
+  --trace_output_dir ./open_deep_research_trace_manual \
+  --enable_statistics
+```
+
+## Trace replay
+
+For replaying recorded traces, use the general scripts under `examples/scaffolding/trace_replay`.
diff --git a/examples/scaffolding/contrib/open_deep_research/TavilyMCP/README.md b/examples/scaffolding/contrib/open_deep_research/TavilyMCP/README.md
deleted file mode 100644
index cc669c456b16..000000000000
--- a/examples/scaffolding/contrib/open_deep_research/TavilyMCP/README.md
+++ /dev/null
@@ -1,10 +0,0 @@
-# Tavily MCP
-
-This is a MCP server for the Tavily API. It is used to search the web for information.
-
-## Usage
-
-```
-export TAVILY_API_KEY=<your_api_key>
-uv run travily.py
-```
diff --git a/examples/scaffolding/contrib/open_deep_research/TavilyMCP/pyproject.toml b/examples/scaffolding/contrib/open_deep_research/TavilyMCP/pyproject.toml
deleted file mode 100644
index 72c393bf5b9c..000000000000
--- a/examples/scaffolding/contrib/open_deep_research/TavilyMCP/pyproject.toml
+++ /dev/null
@@ -1,12 +0,0 @@
-[project]
-name = "TavilyMCP"
-version = "0.1.0"
-description = "An MCP server for searching information"
-readme = "README.md"
-requires-python = ">=3.12"
-dependencies = [
-    "httpx>=0.28.1",
-    "mcp[cli]>=1.9.0",
-    "openai>=1.79.0",
-    "tavily-python",
-]
diff --git a/examples/scaffolding/contrib/open_deep_research/TavilyMCP/travily.py b/examples/scaffolding/contrib/open_deep_research/TavilyMCP/travily.py
deleted file mode 100644
index 214acdaf9d17..000000000000
--- a/examples/scaffolding/contrib/open_deep_research/TavilyMCP/travily.py
+++ /dev/null
@@ -1,74 +0,0 @@
-import asyncio
-import logging
-import os
-
-import uvicorn
-from mcp.server import Server
-from mcp.server.fastmcp import FastMCP
-from mcp.server.sse import SseServerTransport
-from starlette.applications import Starlette
-from starlette.requests import Request
-from starlette.responses import Response
-from starlette.routing import Mount, Route
-from tavily import TavilyClient
-
-logging.basicConfig(level=logging.INFO)
-LOGGER = logging.getLogger(__name__)
-
-# Initialize FastMCP server for Weather tools (SSE)
-mcp = FastMCP("tavily_search")
-
-
-@mcp.tool()
-async def web_search(query: str) -> str:
-    TAVILY_API_KEY = os.getenv("TAVILY_API_KEY")
-
-    client = TavilyClient(TAVILY_API_KEY)
-
-    response = await asyncio.to_thread(client.search, query=query)
-    search_result = ""
-    for result in response["results"]:
-        search_result += f"{result['title']}: {result['content']}\n"
-    return search_result
-
-
-def create_starlette_app(mcp_server: Server, *, debug: bool = False) -> Starlette:
-    """Create a Starlette application that can server the provided mcp server with SSE."""
-    sse = SseServerTransport("/messages/")
-
-    async def handle_sse(request: Request) -> Response:
-        async with sse.connect_sse(
-            request.scope,
-            request.receive,
-            request._send,  # noqa: SLF001
-        ) as (read_stream, write_stream):
-            await mcp_server.run(
-                read_stream,
-                write_stream,
-                mcp_server.create_initialization_options(),
-            )
-        return Response()
-
-    return Starlette(
-        debug=debug,
-        routes=[
-            Route("/sse", endpoint=handle_sse),
-            Mount("/messages/", app=sse.handle_post_message),
-        ],
-    )
-
-
-if __name__ == "__main__":
-    mcp_server = mcp._mcp_server  # noqa: WPS437
-
-    import argparse
-
-    parser = argparse.ArgumentParser(description="Run MCP SSE-based server")
-    parser.add_argument("--host", default="0.0.0.0", help="Host to bind to")
-    parser.add_argument("--port", type=int, default=8082, help="Port to listen on")
-    args = parser.parse_args()
-
-    # Bind SSE request handling to MCP server
-    starlette_app = create_starlette_app(mcp_server, debug=True)
-
-    uvicorn.run(starlette_app, host=args.host, port=args.port)
diff --git a/examples/scaffolding/contrib/open_deep_research/TavilyMCP/uv.lock b/examples/scaffolding/contrib/open_deep_research/TavilyMCP/uv.lock
deleted file mode 100644
index 1dd8954cccaa..000000000000
--- a/examples/scaffolding/contrib/open_deep_research/TavilyMCP/uv.lock
+++ /dev/null
@@ -1,1065 +0,0 @@
-version = 1
-revision = 3
-requires-python = ">=3.12"
-
-[[package]]
-name = "annotated-doc"
-version = "0.0.4"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/57/ba/046ceea27344560984e26a590f90bc7f4a75b06701f653222458922b558c/annotated_doc-0.0.4.tar.gz", hash = "sha256:fbcda96e87e9c92ad167c2e53839e57503ecfda18804ea28102353485033faa4", size = 7288, upload-time = "2025-11-10T22:07:42.062Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/1e/d3/26bf1008eb3d2daa8ef4cacc7f3bfdc11818d111f7e2d0201bc6e3b49d45/annotated_doc-0.0.4-py3-none-any.whl", hash = "sha256:571ac1dc6991c450b25a9c2d84a3705e2ae7a53467b5d111c24fa8baabbed320", size = 5303, upload-time = "2025-11-10T22:07:40.673Z" },
-]
-
-[[package]]
-name = "annotated-types"
-version = "0.7.0"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/ee/67/531ea369ba64dcff5ec9c3402f9f51bf748cec26dde048a2f973a4eea7f5/annotated_types-0.7.0.tar.gz", hash = "sha256:aff07c09a53a08bc8cfccb9c85b05f1aa9a2a6f23728d790723543408344ce89", size = 16081, upload-time = "2024-05-20T21:33:25.928Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/78/b6/6307fbef88d9b5ee7421e68d78a9f162e0da4900bc5f5793f6d3d0e34fb8/annotated_types-0.7.0-py3-none-any.whl", hash = "sha256:1f02e8b43a8fbbc3f3e0d4f0f4bfc8131bcb4eebe8849b8e5c773f3a1c582a53", size = 13643, upload-time = "2024-05-20T21:33:24.1Z" },
-]
-
-[[package]]
-name = "anyio"
-version = "4.13.0"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "idna" },
-    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/19/14/2c5dd9f512b66549ae92767a9c7b330ae88e1932ca57876909410251fe13/anyio-4.13.0.tar.gz", hash = "sha256:334b70e641fd2221c1505b3890c69882fe4a2df910cba14d97019b90b24439dc", size = 231622, upload-time = "2026-03-24T12:59:09.671Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/da/42/e921fccf5015463e32a3cf6ee7f980a6ed0f395ceeaa45060b61d86486c2/anyio-4.13.0-py3-none-any.whl", hash = "sha256:08b310f9e24a9594186fd75b4f73f4a4152069e3853f1ed8bfbf58369f4ad708", size = 114353, upload-time = "2026-03-24T12:59:08.246Z" },
-]
-
-[[package]]
-name = "attrs"
-version = "26.1.0"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/9a/8e/82a0fe20a541c03148528be8cac2408564a6c9a0cc7e9171802bc1d26985/attrs-26.1.0.tar.gz", hash = "sha256:d03ceb89cb322a8fd706d4fb91940737b6642aa36998fe130a9bc96c985eff32", size = 952055, upload-time = "2026-03-19T14:22:25.026Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/64/b4/17d4b0b2a2dc85a6df63d1157e028ed19f90d4cd97c36717afef2bc2f395/attrs-26.1.0-py3-none-any.whl", hash = "sha256:c647aa4a12dfbad9333ca4e71fe62ddc36f4e63b2d260a37a8b83d2f043ac309", size = 67548, upload-time = "2026-03-19T14:22:23.645Z" },
-]
-
-[[package]]
-name = "certifi"
-version = "2026.4.22"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/25/ee/6caf7a40c36a1220410afe15a1cc64993a1f864871f698c0f93acb72842a/certifi-2026.4.22.tar.gz", hash = "sha256:8d455352a37b71bf76a79caa83a3d6c25afee4a385d632127b6afb3963f1c580", size = 137077, upload-time = "2026-04-22T11:26:11.191Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/22/30/7cd8fdcdfbc5b869528b079bfb76dcdf6056b1a2097a662e5e8c04f42965/certifi-2026.4.22-py3-none-any.whl", hash = "sha256:3cb2210c8f88ba2318d29b0388d1023c8492ff72ecdde4ebdaddbb13a31b1c4a", size = 135707, upload-time = "2026-04-22T11:26:09.372Z" },
-]
-
-[[package]]
-name = "cffi"
-version = "2.0.0"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "pycparser", marker = "implementation_name != 'PyPy'" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/eb/56/b1ba7935a17738ae8453301356628e8147c79dbb825bcbc73dc7401f9846/cffi-2.0.0.tar.gz", hash = "sha256:44d1b5909021139fe36001ae048dbdde8214afa20200eda0f64c068cac5d5529", size = 523588, upload-time = "2025-09-08T23:24:04.541Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/ea/47/4f61023ea636104d4f16ab488e268b93008c3d0bb76893b1b31db1f96802/cffi-2.0.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:6d02d6655b0e54f54c4ef0b94eb6be0607b70853c45ce98bd278dc7de718be5d", size = 185271, upload-time = "2025-09-08T23:22:44.795Z" },
-    { url = "https://files.pythonhosted.org/packages/df/a2/781b623f57358e360d62cdd7a8c681f074a71d445418a776eef0aadb4ab4/cffi-2.0.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:8eca2a813c1cb7ad4fb74d368c2ffbbb4789d377ee5bb8df98373c2cc0dee76c", size = 181048, upload-time = "2025-09-08T23:22:45.938Z" },
-    { url = "https://files.pythonhosted.org/packages/ff/df/a4f0fbd47331ceeba3d37c2e51e9dfc9722498becbeec2bd8bc856c9538a/cffi-2.0.0-cp312-cp312-manylinux1_i686.manylinux2014_i686.manylinux_2_17_i686.manylinux_2_5_i686.whl", hash = "sha256:21d1152871b019407d8ac3985f6775c079416c282e431a4da6afe7aefd2bccbe", size = 212529, upload-time = "2025-09-08T23:22:47.349Z" },
-    { url = "https://files.pythonhosted.org/packages/d5/72/12b5f8d3865bf0f87cf1404d8c374e7487dcf097a1c91c436e72e6badd83/cffi-2.0.0-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:b21e08af67b8a103c71a250401c78d5e0893beff75e28c53c98f4de42f774062", size = 220097, upload-time = "2025-09-08T23:22:48.677Z" },
-    { url = "https://files.pythonhosted.org/packages/c2/95/7a135d52a50dfa7c882ab0ac17e8dc11cec9d55d2c18dda414c051c5e69e/cffi-2.0.0-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:1e3a615586f05fc4065a8b22b8152f0c1b00cdbc60596d187c2a74f9e3036e4e", size = 207983, upload-time = "2025-09-08T23:22:50.06Z" },
-    { url = "https://files.pythonhosted.org/packages/3a/c8/15cb9ada8895957ea171c62dc78ff3e99159ee7adb13c0123c001a2546c1/cffi-2.0.0-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:81afed14892743bbe14dacb9e36d9e0e504cd204e0b165062c488942b9718037", size = 206519, upload-time = "2025-09-08T23:22:51.364Z" },
-    { url = "https://files.pythonhosted.org/packages/78/2d/7fa73dfa841b5ac06c7b8855cfc18622132e365f5b81d02230333ff26e9e/cffi-2.0.0-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:3e17ed538242334bf70832644a32a7aae3d83b57567f9fd60a26257e992b79ba", size = 219572, upload-time = "2025-09-08T23:22:52.902Z" },
-    { url = "https://files.pythonhosted.org/packages/07/e0/267e57e387b4ca276b90f0434ff88b2c2241ad72b16d31836adddfd6031b/cffi-2.0.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:3925dd22fa2b7699ed2617149842d2e6adde22b262fcbfada50e3d195e4b3a94", size = 222963, upload-time = "2025-09-08T23:22:54.518Z" },
-    { url = "https://files.pythonhosted.org/packages/b6/75/1f2747525e06f53efbd878f4d03bac5b859cbc11c633d0fb81432d98a795/cffi-2.0.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:2c8f814d84194c9ea681642fd164267891702542f028a15fc97d4674b6206187", size = 221361, upload-time = "2025-09-08T23:22:55.867Z" },
-    { url = "https://files.pythonhosted.org/packages/7b/2b/2b6435f76bfeb6bbf055596976da087377ede68df465419d192acf00c437/cffi-2.0.0-cp312-cp312-win32.whl", hash = "sha256:da902562c3e9c550df360bfa53c035b2f241fed6d9aef119048073680ace4a18", size = 172932, upload-time = "2025-09-08T23:22:57.188Z" },
-    { url = "https://files.pythonhosted.org/packages/f8/ed/13bd4418627013bec4ed6e54283b1959cf6db888048c7cf4b4c3b5b36002/cffi-2.0.0-cp312-cp312-win_amd64.whl", hash = "sha256:da68248800ad6320861f129cd9c1bf96ca849a2771a59e0344e88681905916f5", size = 183557, upload-time = "2025-09-08T23:22:58.351Z" },
-    { url = "https://files.pythonhosted.org/packages/95/31/9f7f93ad2f8eff1dbc1c3656d7ca5bfd8fb52c9d786b4dcf19b2d02217fa/cffi-2.0.0-cp312-cp312-win_arm64.whl", hash = "sha256:4671d9dd5ec934cb9a73e7ee9676f9362aba54f7f34910956b84d727b0d73fb6", size = 177762, upload-time = "2025-09-08T23:22:59.668Z" },
-    { url = "https://files.pythonhosted.org/packages/4b/8d/a0a47a0c9e413a658623d014e91e74a50cdd2c423f7ccfd44086ef767f90/cffi-2.0.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:00bdf7acc5f795150faa6957054fbbca2439db2f775ce831222b66f192f03beb", size = 185230, upload-time = "2025-09-08T23:23:00.879Z" },
-    { url = "https://files.pythonhosted.org/packages/4a/d2/a6c0296814556c68ee32009d9c2ad4f85f2707cdecfd7727951ec228005d/cffi-2.0.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:45d5e886156860dc35862657e1494b9bae8dfa63bf56796f2fb56e1679fc0bca", size = 181043, upload-time = "2025-09-08T23:23:02.231Z" },
-    { url = "https://files.pythonhosted.org/packages/b0/1e/d22cc63332bd59b06481ceaac49d6c507598642e2230f201649058a7e704/cffi-2.0.0-cp313-cp313-manylinux1_i686.manylinux2014_i686.manylinux_2_17_i686.manylinux_2_5_i686.whl", hash = "sha256:07b271772c100085dd28b74fa0cd81c8fb1a3ba18b21e03d7c27f3436a10606b", size = 212446, upload-time = "2025-09-08T23:23:03.472Z" },
-    { url = "https://files.pythonhosted.org/packages/a9/f5/a2c23eb03b61a0b8747f211eb716446c826ad66818ddc7810cc2cc19b3f2/cffi-2.0.0-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:d48a880098c96020b02d5a1f7d9251308510ce8858940e6fa99ece33f610838b", size = 220101, upload-time = "2025-09-08T23:23:04.792Z" },
-    { url = "https://files.pythonhosted.org/packages/f2/7f/e6647792fc5850d634695bc0e6ab4111ae88e89981d35ac269956605feba/cffi-2.0.0-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:f93fd8e5c8c0a4aa1f424d6173f14a892044054871c771f8566e4008eaa359d2", size = 207948, upload-time = "2025-09-08T23:23:06.127Z" },
-    { url = "https://files.pythonhosted.org/packages/cb/1e/a5a1bd6f1fb30f22573f76533de12a00bf274abcdc55c8edab639078abb6/cffi-2.0.0-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:dd4f05f54a52fb558f1ba9f528228066954fee3ebe629fc1660d874d040ae5a3", size = 206422, upload-time = "2025-09-08T23:23:07.753Z" },
-    { url = "https://files.pythonhosted.org/packages/98/df/0a1755e750013a2081e863e7cd37e0cdd02664372c754e5560099eb7aa44/cffi-2.0.0-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:c8d3b5532fc71b7a77c09192b4a5a200ea992702734a2e9279a37f2478236f26", size = 219499, upload-time = "2025-09-08T23:23:09.648Z" },
-    { url = "https://files.pythonhosted.org/packages/50/e1/a969e687fcf9ea58e6e2a928ad5e2dd88cc12f6f0ab477e9971f2309b57c/cffi-2.0.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:d9b29c1f0ae438d5ee9acb31cadee00a58c46cc9c0b2f9038c6b0b3470877a8c", size = 222928, upload-time = "2025-09-08T23:23:10.928Z" },
-    { url = "https://files.pythonhosted.org/packages/36/54/0362578dd2c9e557a28ac77698ed67323ed5b9775ca9d3fe73fe191bb5d8/cffi-2.0.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:6d50360be4546678fc1b79ffe7a66265e28667840010348dd69a314145807a1b", size = 221302, upload-time = "2025-09-08T23:23:12.42Z" },
-    { url = "https://files.pythonhosted.org/packages/eb/6d/bf9bda840d5f1dfdbf0feca87fbdb64a918a69bca42cfa0ba7b137c48cb8/cffi-2.0.0-cp313-cp313-win32.whl", hash = "sha256:74a03b9698e198d47562765773b4a8309919089150a0bb17d829ad7b44b60d27", size = 172909, upload-time = "2025-09-08T23:23:14.32Z" },
-    { url = "https://files.pythonhosted.org/packages/37/18/6519e1ee6f5a1e579e04b9ddb6f1676c17368a7aba48299c3759bbc3c8b3/cffi-2.0.0-cp313-cp313-win_amd64.whl", hash = "sha256:19f705ada2530c1167abacb171925dd886168931e0a7b78f5bffcae5c6b5be75", size = 183402, upload-time = "2025-09-08T23:23:15.535Z" },
-    { url = "https://files.pythonhosted.org/packages/cb/0e/02ceeec9a7d6ee63bb596121c2c8e9b3a9e150936f4fbef6ca1943e6137c/cffi-2.0.0-cp313-cp313-win_arm64.whl", hash = "sha256:256f80b80ca3853f90c21b23ee78cd008713787b1b1e93eae9f3d6a7134abd91", size = 177780, upload-time = "2025-09-08T23:23:16.761Z" },
-    { url = "https://files.pythonhosted.org/packages/92/c4/3ce07396253a83250ee98564f8d7e9789fab8e58858f35d07a9a2c78de9f/cffi-2.0.0-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:fc33c5141b55ed366cfaad382df24fe7dcbc686de5be719b207bb248e3053dc5", size = 185320, upload-time = "2025-09-08T23:23:18.087Z" },
-    { url = "https://files.pythonhosted.org/packages/59/dd/27e9fa567a23931c838c6b02d0764611c62290062a6d4e8ff7863daf9730/cffi-2.0.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:c654de545946e0db659b3400168c9ad31b5d29593291482c43e3564effbcee13", size = 181487, upload-time = "2025-09-08T23:23:19.622Z" },
-    { url = "https://files.pythonhosted.org/packages/d6/43/0e822876f87ea8a4ef95442c3d766a06a51fc5298823f884ef87aaad168c/cffi-2.0.0-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:24b6f81f1983e6df8db3adc38562c83f7d4a0c36162885ec7f7b77c7dcbec97b", size = 220049, upload-time = "2025-09-08T23:23:20.853Z" },
-    { url = "https://files.pythonhosted.org/packages/b4/89/76799151d9c2d2d1ead63c2429da9ea9d7aac304603de0c6e8764e6e8e70/cffi-2.0.0-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:12873ca6cb9b0f0d3a0da705d6086fe911591737a59f28b7936bdfed27c0d47c", size = 207793, upload-time = "2025-09-08T23:23:22.08Z" },
-    { url = "https://files.pythonhosted.org/packages/bb/dd/3465b14bb9e24ee24cb88c9e3730f6de63111fffe513492bf8c808a3547e/cffi-2.0.0-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:d9b97165e8aed9272a6bb17c01e3cc5871a594a446ebedc996e2397a1c1ea8ef", size = 206300, upload-time = "2025-09-08T23:23:23.314Z" },
-    { url = "https://files.pythonhosted.org/packages/47/d9/d83e293854571c877a92da46fdec39158f8d7e68da75bf73581225d28e90/cffi-2.0.0-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:afb8db5439b81cf9c9d0c80404b60c3cc9c3add93e114dcae767f1477cb53775", size = 219244, upload-time = "2025-09-08T23:23:24.541Z" },
-    { url = "https://files.pythonhosted.org/packages/2b/0f/1f177e3683aead2bb00f7679a16451d302c436b5cbf2505f0ea8146ef59e/cffi-2.0.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:737fe7d37e1a1bffe70bd5754ea763a62a066dc5913ca57e957824b72a85e205", size = 222828, upload-time = "2025-09-08T23:23:26.143Z" },
-    { url = "https://files.pythonhosted.org/packages/c6/0f/cafacebd4b040e3119dcb32fed8bdef8dfe94da653155f9d0b9dc660166e/cffi-2.0.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:38100abb9d1b1435bc4cc340bb4489635dc2f0da7456590877030c9b3d40b0c1", size = 220926, upload-time = "2025-09-08T23:23:27.873Z" },
-    { url = "https://files.pythonhosted.org/packages/3e/aa/df335faa45b395396fcbc03de2dfcab242cd61a9900e914fe682a59170b1/cffi-2.0.0-cp314-cp314-win32.whl", hash = "sha256:087067fa8953339c723661eda6b54bc98c5625757ea62e95eb4898ad5e776e9f", size = 175328, upload-time = "2025-09-08T23:23:44.61Z" },
-    { url = "https://files.pythonhosted.org/packages/bb/92/882c2d30831744296ce713f0feb4c1cd30f346ef747b530b5318715cc367/cffi-2.0.0-cp314-cp314-win_amd64.whl", hash = "sha256:203a48d1fb583fc7d78a4c6655692963b860a417c0528492a6bc21f1aaefab25", size = 185650, upload-time = "2025-09-08T23:23:45.848Z" },
-    { url = "https://files.pythonhosted.org/packages/9f/2c/98ece204b9d35a7366b5b2c6539c350313ca13932143e79dc133ba757104/cffi-2.0.0-cp314-cp314-win_arm64.whl", hash = "sha256:dbd5c7a25a7cb98f5ca55d258b103a2054f859a46ae11aaf23134f9cc0d356ad", size = 180687, upload-time = "2025-09-08T23:23:47.105Z" },
-    { url = "https://files.pythonhosted.org/packages/3e/61/c768e4d548bfa607abcda77423448df8c471f25dbe64fb2ef6d555eae006/cffi-2.0.0-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:9a67fc9e8eb39039280526379fb3a70023d77caec1852002b4da7e8b270c4dd9", size = 188773, upload-time = "2025-09-08T23:23:29.347Z" },
-    { url = "https://files.pythonhosted.org/packages/2c/ea/5f76bce7cf6fcd0ab1a1058b5af899bfbef198bea4d5686da88471ea0336/cffi-2.0.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:7a66c7204d8869299919db4d5069a82f1561581af12b11b3c9f48c584eb8743d", size = 185013, upload-time = "2025-09-08T23:23:30.63Z" },
-    { url = "https://files.pythonhosted.org/packages/be/b4/c56878d0d1755cf9caa54ba71e5d049479c52f9e4afc230f06822162ab2f/cffi-2.0.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:7cc09976e8b56f8cebd752f7113ad07752461f48a58cbba644139015ac24954c", size = 221593, upload-time = "2025-09-08T23:23:31.91Z" },
-    { url = "https://files.pythonhosted.org/packages/e0/0d/eb704606dfe8033e7128df5e90fee946bbcb64a04fcdaa97321309004000/cffi-2.0.0-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:92b68146a71df78564e4ef48af17551a5ddd142e5190cdf2c5624d0c3ff5b2e8", size = 209354, upload-time = "2025-09-08T23:23:33.214Z" },
-    { url = "https://files.pythonhosted.org/packages/d8/19/3c435d727b368ca475fb8742ab97c9cb13a0de600ce86f62eab7fa3eea60/cffi-2.0.0-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:b1e74d11748e7e98e2f426ab176d4ed720a64412b6a15054378afdb71e0f37dc", size = 208480, upload-time = "2025-09-08T23:23:34.495Z" },
-    { url = "https://files.pythonhosted.org/packages/d0/44/681604464ed9541673e486521497406fadcc15b5217c3e326b061696899a/cffi-2.0.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:28a3a209b96630bca57cce802da70c266eb08c6e97e5afd61a75611ee6c64592", size = 221584, upload-time = "2025-09-08T23:23:36.096Z" },
-    { url = "https://files.pythonhosted.org/packages/25/8e/342a504ff018a2825d395d44d63a767dd8ebc927ebda557fecdaca3ac33a/cffi-2.0.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:7553fb2090d71822f02c629afe6042c299edf91ba1bf94951165613553984512", size = 224443, upload-time = "2025-09-08T23:23:37.328Z" },
-    { url = "https://files.pythonhosted.org/packages/e1/5e/b666bacbbc60fbf415ba9988324a132c9a7a0448a9a8f125074671c0f2c3/cffi-2.0.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:6c6c373cfc5c83a975506110d17457138c8c63016b563cc9ed6e056a82f13ce4", size = 223437, upload-time = "2025-09-08T23:23:38.945Z" },
-    { url = "https://files.pythonhosted.org/packages/a0/1d/ec1a60bd1a10daa292d3cd6bb0b359a81607154fb8165f3ec95fe003b85c/cffi-2.0.0-cp314-cp314t-win32.whl", hash = "sha256:1fc9ea04857caf665289b7a75923f2c6ed559b8298a1b8c49e59f7dd95c8481e", size = 180487, upload-time = "2025-09-08T23:23:40.423Z" },
-    { url = "https://files.pythonhosted.org/packages/bf/41/4c1168c74fac325c0c8156f04b6749c8b6a8f405bbf91413ba088359f60d/cffi-2.0.0-cp314-cp314t-win_amd64.whl", hash = "sha256:d68b6cef7827e8641e8ef16f4494edda8b36104d79773a334beaa1e3521430f6", size = 191726, upload-time = "2025-09-08T23:23:41.742Z" },
-    { url = "https://files.pythonhosted.org/packages/ae/3a/dbeec9d1ee0844c679f6bb5d6ad4e9f198b1224f4e7a32825f47f6192b0c/cffi-2.0.0-cp314-cp314t-win_arm64.whl", hash = "sha256:0a1527a803f0a659de1af2e1fd700213caba79377e27e4693648c2923da066f9", size = 184195, upload-time = "2025-09-08T23:23:43.004Z" },
-]
-
-[[package]]
-name = "charset-normalizer"
-version = "3.4.7"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/e7/a1/67fe25fac3c7642725500a3f6cfe5821ad557c3abb11c9d20d12c7008d3e/charset_normalizer-3.4.7.tar.gz", hash = "sha256:ae89db9e5f98a11a4bf50407d4363e7b09b31e55bc117b4f7d80aab97ba009e5", size = 144271, upload-time = "2026-04-02T09:28:39.342Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/0c/eb/4fc8d0a7110eb5fc9cc161723a34a8a6c200ce3b4fbf681bc86feee22308/charset_normalizer-3.4.7-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:eca9705049ad3c7345d574e3510665cb2cf844c2f2dcfe675332677f081cbd46", size = 311328, upload-time = "2026-04-02T09:26:24.331Z" },
-    { url = "https://files.pythonhosted.org/packages/f8/e3/0fadc706008ac9d7b9b5be6dc767c05f9d3e5df51744ce4cc9605de7b9f4/charset_normalizer-3.4.7-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:6178f72c5508bfc5fd446a5905e698c6212932f25bcdd4b47a757a50605a90e2", size = 208061, upload-time = "2026-04-02T09:26:25.568Z" },
-    { url = "https://files.pythonhosted.org/packages/42/f0/3dd1045c47f4a4604df85ec18ad093912ae1344ac706993aff91d38773a2/charset_normalizer-3.4.7-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:e1421b502d83040e6d7fb2fb18dff63957f720da3d77b2fbd3187ceb63755d7b", size = 229031, upload-time = "2026-04-02T09:26:26.865Z" },
-    { url = "https://files.pythonhosted.org/packages/dc/67/675a46eb016118a2fbde5a277a5d15f4f69d5f3f5f338e5ee2f8948fcf43/charset_normalizer-3.4.7-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:edac0f1ab77644605be2cbba52e6b7f630731fc42b34cb0f634be1a6eface56a", size = 225239, upload-time = "2026-04-02T09:26:28.044Z" },
-    { url = "https://files.pythonhosted.org/packages/4b/f8/d0118a2f5f23b02cd166fa385c60f9b0d4f9194f574e2b31cef350ad7223/charset_normalizer-3.4.7-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:5649fd1c7bade02f320a462fdefd0b4bd3ce036065836d4f42e0de958038e116", size = 216589, upload-time = "2026-04-02T09:26:29.239Z" },
-    { url = "https://files.pythonhosted.org/packages/b1/f1/6d2b0b261b6c4ceef0fcb0d17a01cc5bc53586c2d4796fa04b5c540bc13d/charset_normalizer-3.4.7-cp312-cp312-manylinux_2_31_armv7l.whl", hash = "sha256:203104ed3e428044fd943bc4bf45fa73c0730391f9621e37fe39ecf477b128cb", size = 202733, upload-time = "2026-04-02T09:26:30.5Z" },
-    { url = "https://files.pythonhosted.org/packages/6f/c0/7b1f943f7e87cc3db9626ba17807d042c38645f0a1d4415c7a14afb5591f/charset_normalizer-3.4.7-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:298930cec56029e05497a76988377cbd7457ba864beeea92ad7e844fe74cd1f1", size = 212652, upload-time = "2026-04-02T09:26:31.709Z" },
-    { url = "https://files.pythonhosted.org/packages/38/dd/5a9ab159fe45c6e72079398f277b7d2b523e7f716acc489726115a910097/charset_normalizer-3.4.7-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:708838739abf24b2ceb208d0e22403dd018faeef86ddac04319a62ae884c4f15", size = 211229, upload-time = "2026-04-02T09:26:33.282Z" },
-    { url = "https://files.pythonhosted.org/packages/d5/ff/531a1cad5ca855d1c1a8b69cb71abfd6d85c0291580146fda7c82857caa1/charset_normalizer-3.4.7-cp312-cp312-musllinux_1_2_armv7l.whl", hash = "sha256:0f7eb884681e3938906ed0434f20c63046eacd0111c4ba96f27b76084cd679f5", size = 203552, upload-time = "2026-04-02T09:26:34.845Z" },
-    { url = "https://files.pythonhosted.org/packages/c1/4c/a5fb52d528a8ca41f7598cb619409ece30a169fbdf9cdce592e53b46c3a6/charset_normalizer-3.4.7-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:4dc1e73c36828f982bfe79fadf5919923f8a6f4df2860804db9a98c48824ce8d", size = 230806, upload-time = "2026-04-02T09:26:36.152Z" },
-    { url = "https://files.pythonhosted.org/packages/59/7a/071feed8124111a32b316b33ae4de83d36923039ef8cf48120266844285b/charset_normalizer-3.4.7-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:aed52fea0513bac0ccde438c188c8a471c4e0f457c2dd20cdbf6ea7a450046c7", size = 212316, upload-time = "2026-04-02T09:26:37.672Z" },
-    { url = "https://files.pythonhosted.org/packages/fd/35/f7dba3994312d7ba508e041eaac39a36b120f32d4c8662b8814dab876431/charset_normalizer-3.4.7-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:fea24543955a6a729c45a73fe90e08c743f0b3334bbf3201e6c4bc1b0c7fa464", size = 227274, upload-time = "2026-04-02T09:26:38.93Z" },
-    { url = "https://files.pythonhosted.org/packages/8a/2d/a572df5c9204ab7688ec1edc895a73ebded3b023bb07364710b05dd1c9be/charset_normalizer-3.4.7-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:bb6d88045545b26da47aa879dd4a89a71d1dce0f0e549b1abcb31dfe4a8eac49", size = 218468, upload-time = "2026-04-02T09:26:40.17Z" },
-    { url = "https://files.pythonhosted.org/packages/86/eb/890922a8b03a568ca2f336c36585a4713c55d4d67bf0f0c78924be6315ca/charset_normalizer-3.4.7-cp312-cp312-win32.whl", hash = "sha256:2257141f39fe65a3fdf38aeccae4b953e5f3b3324f4ff0daf9f15b8518666a2c", size = 148460, upload-time = "2026-04-02T09:26:41.416Z" },
-    { url = "https://files.pythonhosted.org/packages/35/d9/0e7dffa06c5ab081f75b1b786f0aefc88365825dfcd0ac544bdb7b2b6853/charset_normalizer-3.4.7-cp312-cp312-win_amd64.whl", hash = "sha256:5ed6ab538499c8644b8a3e18debabcd7ce684f3fa91cf867521a7a0279cab2d6", size = 159330, upload-time = "2026-04-02T09:26:42.554Z" },
-    { url = "https://files.pythonhosted.org/packages/9e/5d/481bcc2a7c88ea6b0878c299547843b2521ccbc40980cb406267088bc701/charset_normalizer-3.4.7-cp312-cp312-win_arm64.whl", hash = "sha256:56be790f86bfb2c98fb742ce566dfb4816e5a83384616ab59c49e0604d49c51d", size = 147828, upload-time = "2026-04-02T09:26:44.075Z" },
-    { url = "https://files.pythonhosted.org/packages/c1/3b/66777e39d3ae1ddc77ee606be4ec6d8cbd4c801f65e5a1b6f2b11b8346dd/charset_normalizer-3.4.7-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:f496c9c3cc02230093d8330875c4c3cdfc3b73612a5fd921c65d39cbcef08063", size = 309627, upload-time = "2026-04-02T09:26:45.198Z" },
-    { url = "https://files.pythonhosted.org/packages/2e/4e/b7f84e617b4854ade48a1b7915c8ccfadeba444d2a18c291f696e37f0d3b/charset_normalizer-3.4.7-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:0ea948db76d31190bf08bd371623927ee1339d5f2a0b4b1b4a4439a65298703c", size = 207008, upload-time = "2026-04-02T09:26:46.824Z" },
-    { url = "https://files.pythonhosted.org/packages/c4/bb/ec73c0257c9e11b268f018f068f5d00aa0ef8c8b09f7753ebd5f2880e248/charset_normalizer-3.4.7-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:a277ab8928b9f299723bc1a2dabb1265911b1a76341f90a510368ca44ad9ab66", size = 228303, upload-time = "2026-04-02T09:26:48.397Z" },
-    { url = "https://files.pythonhosted.org/packages/85/fb/32d1f5033484494619f701e719429c69b766bfc4dbc61aa9e9c8c166528b/charset_normalizer-3.4.7-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:3bec022aec2c514d9cf199522a802bd007cd588ab17ab2525f20f9c34d067c18", size = 224282, upload-time = "2026-04-02T09:26:49.684Z" },
-    { url = "https://files.pythonhosted.org/packages/fa/07/330e3a0dda4c404d6da83b327270906e9654a24f6c546dc886a0eb0ffb23/charset_normalizer-3.4.7-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:e044c39e41b92c845bc815e5ae4230804e8e7bc29e399b0437d64222d92809dd", size = 215595, upload-time = "2026-04-02T09:26:50.915Z" },
-    { url = "https://files.pythonhosted.org/packages/e3/7c/fc890655786e423f02556e0216d4b8c6bcb6bdfa890160dc66bf52dee468/charset_normalizer-3.4.7-cp313-cp313-manylinux_2_31_armv7l.whl", hash = "sha256:f495a1652cf3fbab2eb0639776dad966c2fb874d79d87ca07f9d5f059b8bd215", size = 201986, upload-time = "2026-04-02T09:26:52.197Z" },
-    { url = "https://files.pythonhosted.org/packages/d8/97/bfb18b3db2aed3b90cf54dc292ad79fdd5ad65c4eae454099475cbeadd0d/charset_normalizer-3.4.7-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:e712b419df8ba5e42b226c510472b37bd57b38e897d3eca5e8cfd410a29fa859", size = 211711, upload-time = "2026-04-02T09:26:53.49Z" },
-    { url = "https://files.pythonhosted.org/packages/6f/a5/a581c13798546a7fd557c82614a5c65a13df2157e9ad6373166d2a3e645d/charset_normalizer-3.4.7-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:7804338df6fcc08105c7745f1502ba68d900f45fd770d5bdd5288ddccb8a42d8", size = 210036, upload-time = "2026-04-02T09:26:54.975Z" },
-    { url = "https://files.pythonhosted.org/packages/8c/bf/b3ab5bcb478e4193d517644b0fb2bf5497fbceeaa7a1bc0f4d5b50953861/charset_normalizer-3.4.7-cp313-cp313-musllinux_1_2_armv7l.whl", hash = "sha256:481551899c856c704d58119b5025793fa6730adda3571971af568f66d2424bb5", size = 202998, upload-time = "2026-04-02T09:26:56.303Z" },
-    { url = "https://files.pythonhosted.org/packages/e7/4e/23efd79b65d314fa320ec6017b4b5834d5c12a58ba4610aa353af2e2f577/charset_normalizer-3.4.7-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:f59099f9b66f0d7145115e6f80dd8b1d847176df89b234a5a6b3f00437aa0832", size = 230056, upload-time = "2026-04-02T09:26:57.554Z" },
-    { url = "https://files.pythonhosted.org/packages/b9/9f/1e1941bc3f0e01df116e68dc37a55c4d249df5e6fa77f008841aef68264f/charset_normalizer-3.4.7-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:f59ad4c0e8f6bba240a9bb85504faa1ab438237199d4cce5f622761507b8f6a6", size = 211537, upload-time = "2026-04-02T09:26:58.843Z" },
-    { url = "https://files.pythonhosted.org/packages/80/0f/088cbb3020d44428964a6c97fe1edfb1b9550396bf6d278330281e8b709c/charset_normalizer-3.4.7-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:3dedcc22d73ec993f42055eff4fcfed9318d1eeb9a6606c55892a26964964e48", size = 226176, upload-time = "2026-04-02T09:27:00.437Z" },
-    { url = "https://files.pythonhosted.org/packages/6a/9f/130394f9bbe06f4f63e22641d32fc9b202b7e251c9aef4db044324dac493/charset_normalizer-3.4.7-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:64f02c6841d7d83f832cd97ccf8eb8a906d06eb95d5276069175c696b024b60a", size = 217723, upload-time = "2026-04-02T09:27:02.021Z" },
-    { url = "https://files.pythonhosted.org/packages/73/55/c469897448a06e49f8fa03f6caae97074fde823f432a98f979cc42b90e69/charset_normalizer-3.4.7-cp313-cp313-win32.whl", hash = "sha256:4042d5c8f957e15221d423ba781e85d553722fc4113f523f2feb7b188cc34c5e", size = 148085, upload-time = "2026-04-02T09:27:03.192Z" },
-    { url = "https://files.pythonhosted.org/packages/5d/78/1b74c5bbb3f99b77a1715c91b3e0b5bdb6fe302d95ace4f5b1bec37b0167/charset_normalizer-3.4.7-cp313-cp313-win_amd64.whl", hash = "sha256:3946fa46a0cf3e4c8cb1cc52f56bb536310d34f25f01ca9b6c16afa767dab110", size = 158819, upload-time = "2026-04-02T09:27:04.454Z" },
-    { url = "https://files.pythonhosted.org/packages/68/86/46bd42279d323deb8687c4a5a811fd548cb7d1de10cf6535d099877a9a9f/charset_normalizer-3.4.7-cp313-cp313-win_arm64.whl", hash = "sha256:80d04837f55fc81da168b98de4f4b797ef007fc8a79ab71c6ec9bc4dd662b15b", size = 147915, upload-time = "2026-04-02T09:27:05.971Z" },
-    { url = "https://files.pythonhosted.org/packages/97/c8/c67cb8c70e19ef1960b97b22ed2a1567711de46c4ddf19799923adc836c2/charset_normalizer-3.4.7-cp314-cp314-macosx_10_15_universal2.whl", hash = "sha256:c36c333c39be2dbca264d7803333c896ab8fa7d4d6f0ab7edb7dfd7aea6e98c0", size = 309234, upload-time = "2026-04-02T09:27:07.194Z" },
-    { url = "https://files.pythonhosted.org/packages/99/85/c091fdee33f20de70d6c8b522743b6f831a2f1cd3ff86de4c6a827c48a76/charset_normalizer-3.4.7-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:1c2aed2e5e41f24ea8ef1590b8e848a79b56f3a5564a65ceec43c9d692dc7d8a", size = 208042, upload-time = "2026-04-02T09:27:08.749Z" },
-    { url = "https://files.pythonhosted.org/packages/87/1c/ab2ce611b984d2fd5d86a5a8a19c1ae26acac6bad967da4967562c75114d/charset_normalizer-3.4.7-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:54523e136b8948060c0fa0bc7b1b50c32c186f2fceee897a495406bb6e311d2b", size = 228706, upload-time = "2026-04-02T09:27:09.951Z" },
-    { url = "https://files.pythonhosted.org/packages/a8/29/2b1d2cb00bf085f59d29eb773ce58ec2d325430f8c216804a0a5cd83cbca/charset_normalizer-3.4.7-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:715479b9a2802ecac752a3b0efa2b0b60285cf962ee38414211abdfccc233b41", size = 224727, upload-time = "2026-04-02T09:27:11.175Z" },
-    { url = "https://files.pythonhosted.org/packages/47/5c/032c2d5a07fe4d4855fea851209cca2b6f03ebeb6d4e3afdb3358386a684/charset_normalizer-3.4.7-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:bd6c2a1c7573c64738d716488d2cdd3c00e340e4835707d8fdb8dc1a66ef164e", size = 215882, upload-time = "2026-04-02T09:27:12.446Z" },
-    { url = "https://files.pythonhosted.org/packages/2c/c2/356065d5a8b78ed04499cae5f339f091946a6a74f91e03476c33f0ab7100/charset_normalizer-3.4.7-cp314-cp314-manylinux_2_31_armv7l.whl", hash = "sha256:c45e9440fb78f8ddabcf714b68f936737a121355bf59f3907f4e17721b9d1aae", size = 200860, upload-time = "2026-04-02T09:27:13.721Z" },
-    { url = "https://files.pythonhosted.org/packages/0c/cd/a32a84217ced5039f53b29f460962abb2d4420def55afabe45b1c3c7483d/charset_normalizer-3.4.7-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:3534e7dcbdcf757da6b85a0bbf5b6868786d5982dd959b065e65481644817a18", size = 211564, upload-time = "2026-04-02T09:27:15.272Z" },
-    { url = "https://files.pythonhosted.org/packages/44/86/58e6f13ce26cc3b8f4a36b94a0f22ae2f00a72534520f4ae6857c4b81f89/charset_normalizer-3.4.7-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:e8ac484bf18ce6975760921bb6148041faa8fef0547200386ea0b52b5d27bf7b", size = 211276, upload-time = "2026-04-02T09:27:16.834Z" },
-    { url = "https://files.pythonhosted.org/packages/8f/fe/d17c32dc72e17e155e06883efa84514ca375f8a528ba2546bee73fc4df81/charset_normalizer-3.4.7-cp314-cp314-musllinux_1_2_armv7l.whl", hash = "sha256:a5fe03b42827c13cdccd08e6c0247b6a6d4b5e3cdc53fd1749f5896adcdc2356", size = 201238, upload-time = "2026-04-02T09:27:18.229Z" },
-    { url = "https://files.pythonhosted.org/packages/6a/29/f33daa50b06525a237451cdb6c69da366c381a3dadcd833fa5676bc468b3/charset_normalizer-3.4.7-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:2d6eb928e13016cea4f1f21d1e10c1cebd5a421bc57ddf5b1142ae3f86824fab", size = 230189, upload-time = "2026-04-02T09:27:19.445Z" },
-    { url = "https://files.pythonhosted.org/packages/b6/6e/52c84015394a6a0bdcd435210a7e944c5f94ea1055f5cc5d56c5fe368e7b/charset_normalizer-3.4.7-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:e74327fb75de8986940def6e8dee4f127cc9752bee7355bb323cc5b2659b6d46", size = 211352, upload-time = "2026-04-02T09:27:20.79Z" },
-    { url = "https://files.pythonhosted.org/packages/8c/d7/4353be581b373033fb9198bf1da3cf8f09c1082561e8e922aa7b39bf9fe8/charset_normalizer-3.4.7-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:d6038d37043bced98a66e68d3aa2b6a35505dc01328cd65217cefe82f25def44", size = 227024, upload-time = "2026-04-02T09:27:22.063Z" },
-    { url = "https://files.pythonhosted.org/packages/30/45/99d18aa925bd1740098ccd3060e238e21115fffbfdcb8f3ece837d0ace6c/charset_normalizer-3.4.7-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:7579e913a5339fb8fa133f6bbcfd8e6749696206cf05acdbdca71a1b436d8e72", size = 217869, upload-time = "2026-04-02T09:27:23.486Z" },
-    { url = "https://files.pythonhosted.org/packages/5c/05/5ee478aa53f4bb7996482153d4bfe1b89e0f087f0ab6b294fcf92d595873/charset_normalizer-3.4.7-cp314-cp314-win32.whl", hash = "sha256:5b77459df20e08151cd6f8b9ef8ef1f961ef73d85c21a555c7eed5b79410ec10", size = 148541, upload-time = "2026-04-02T09:27:25.146Z" },
-    { url = "https://files.pythonhosted.org/packages/48/77/72dcb0921b2ce86420b2d79d454c7022bf5be40202a2a07906b9f2a35c97/charset_normalizer-3.4.7-cp314-cp314-win_amd64.whl", hash = "sha256:92a0a01ead5e668468e952e4238cccd7c537364eb7d851ab144ab6627dbbe12f", size = 159634, upload-time = "2026-04-02T09:27:26.642Z" },
-    { url = "https://files.pythonhosted.org/packages/c6/a3/c2369911cd72f02386e4e340770f6e158c7980267da16af8f668217abaa0/charset_normalizer-3.4.7-cp314-cp314-win_arm64.whl", hash = "sha256:67f6279d125ca0046a7fd386d01b311c6363844deac3e5b069b514ba3e63c246", size = 148384, upload-time = "2026-04-02T09:27:28.271Z" },
-    { url = "https://files.pythonhosted.org/packages/94/09/7e8a7f73d24dba1f0035fbbf014d2c36828fc1bf9c88f84093e57d315935/charset_normalizer-3.4.7-cp314-cp314t-macosx_10_15_universal2.whl", hash = "sha256:effc3f449787117233702311a1b7d8f59cba9ced946ba727bdc329ec69028e24", size = 330133, upload-time = "2026-04-02T09:27:29.474Z" },
-    { url = "https://files.pythonhosted.org/packages/8d/da/96975ddb11f8e977f706f45cddd8540fd8242f71ecdb5d18a80723dcf62c/charset_normalizer-3.4.7-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:fbccdc05410c9ee21bbf16a35f4c1d16123dcdeb8a1d38f33654fa21d0234f79", size = 216257, upload-time = "2026-04-02T09:27:30.793Z" },
-    { url = "https://files.pythonhosted.org/packages/e5/e8/1d63bf8ef2d388e95c64b2098f45f84758f6d102a087552da1485912637b/charset_normalizer-3.4.7-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:733784b6d6def852c814bce5f318d25da2ee65dd4839a0718641c696e09a2960", size = 234851, upload-time = "2026-04-02T09:27:32.44Z" },
-    { url = "https://files.pythonhosted.org/packages/9b/40/e5ff04233e70da2681fa43969ad6f66ca5611d7e669be0246c4c7aaf6dc8/charset_normalizer-3.4.7-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:a89c23ef8d2c6b27fd200a42aa4ac72786e7c60d40efdc76e6011260b6e949c4", size = 233393, upload-time = "2026-04-02T09:27:34.03Z" },
-    { url = "https://files.pythonhosted.org/packages/be/c1/06c6c49d5a5450f76899992f1ee40b41d076aee9279b49cf9974d2f313d5/charset_normalizer-3.4.7-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:6c114670c45346afedc0d947faf3c7f701051d2518b943679c8ff88befe14f8e", size = 223251, upload-time = "2026-04-02T09:27:35.369Z" },
-    { url = "https://files.pythonhosted.org/packages/2b/9f/f2ff16fb050946169e3e1f82134d107e5d4ae72647ec8a1b1446c148480f/charset_normalizer-3.4.7-cp314-cp314t-manylinux_2_31_armv7l.whl", hash = "sha256:a180c5e59792af262bf263b21a3c49353f25945d8d9f70628e73de370d55e1e1", size = 206609, upload-time = "2026-04-02T09:27:36.661Z" },
-    { url = "https://files.pythonhosted.org/packages/69/d5/a527c0cd8d64d2eab7459784fb4169a0ac76e5a6fc5237337982fd61347e/charset_normalizer-3.4.7-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:3c9a494bc5ec77d43cea229c4f6db1e4d8fe7e1bbffa8b6f0f0032430ff8ab44", size = 220014, upload-time = "2026-04-02T09:27:38.019Z" },
-    { url = "https://files.pythonhosted.org/packages/7e/80/8a7b8104a3e203074dc9aa2c613d4b726c0e136bad1cc734594b02867972/charset_normalizer-3.4.7-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:8d828b6667a32a728a1ad1d93957cdf37489c57b97ae6c4de2860fa749b8fc1e", size = 218979, upload-time = "2026-04-02T09:27:39.37Z" },
-    { url = "https://files.pythonhosted.org/packages/02/9a/b759b503d507f375b2b5c153e4d2ee0a75aa215b7f2489cf314f4541f2c0/charset_normalizer-3.4.7-cp314-cp314t-musllinux_1_2_armv7l.whl", hash = "sha256:cf1493cd8607bec4d8a7b9b004e699fcf8f9103a9284cc94962cb73d20f9d4a3", size = 209238, upload-time = "2026-04-02T09:27:40.722Z" },
-    { url = "https://files.pythonhosted.org/packages/c2/4e/0f3f5d47b86bdb79256e7290b26ac847a2832d9a4033f7eb2cd4bcf4bb5b/charset_normalizer-3.4.7-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:0c96c3b819b5c3e9e165495db84d41914d6894d55181d2d108cc1a69bfc9cce0", size = 236110, upload-time = "2026-04-02T09:27:42.33Z" },
-    { url = "https://files.pythonhosted.org/packages/96/23/bce28734eb3ed2c91dcf93abeb8a5cf393a7b2749725030bb630e554fdd8/charset_normalizer-3.4.7-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:752a45dc4a6934060b3b0dab47e04edc3326575f82be64bc4fc293914566503e", size = 219824, upload-time = "2026-04-02T09:27:43.924Z" },
-    { url = "https://files.pythonhosted.org/packages/2c/6f/6e897c6984cc4d41af319b077f2f600fc8214eb2fe2d6bcb79141b882400/charset_normalizer-3.4.7-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:8778f0c7a52e56f75d12dae53ae320fae900a8b9b4164b981b9c5ce059cd1fcb", size = 233103, upload-time = "2026-04-02T09:27:45.348Z" },
-    { url = "https://files.pythonhosted.org/packages/76/22/ef7bd0fe480a0ae9b656189ec00744b60933f68b4f42a7bb06589f6f576a/charset_normalizer-3.4.7-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:ce3412fbe1e31eb81ea42f4169ed94861c56e643189e1e75f0041f3fe7020abe", size = 225194, upload-time = "2026-04-02T09:27:46.706Z" },
-    { url = "https://files.pythonhosted.org/packages/c5/a7/0e0ab3e0b5bc1219bd80a6a0d4d72ca74d9250cb2382b7c699c147e06017/charset_normalizer-3.4.7-cp314-cp314t-win32.whl", hash = "sha256:c03a41a8784091e67a39648f70c5f97b5b6a37f216896d44d2cdcb82615339a0", size = 159827, upload-time = "2026-04-02T09:27:48.053Z" },
-    { url = "https://files.pythonhosted.org/packages/7a/1d/29d32e0fb40864b1f878c7f5a0b343ae676c6e2b271a2d55cc3a152391da/charset_normalizer-3.4.7-cp314-cp314t-win_amd64.whl", hash = "sha256:03853ed82eeebbce3c2abfdbc98c96dc205f32a79627688ac9a27370ea61a49c", size = 174168, upload-time = "2026-04-02T09:27:49.795Z" },
-    { url = "https://files.pythonhosted.org/packages/de/32/d92444ad05c7a6e41fb2036749777c163baf7a0301a040cb672d6b2b1ae9/charset_normalizer-3.4.7-cp314-cp314t-win_arm64.whl", hash = "sha256:c35abb8bfff0185efac5878da64c45dafd2b37fb0383add1be155a763c1f083d", size = 153018, upload-time = "2026-04-02T09:27:51.116Z" },
-    { url = "https://files.pythonhosted.org/packages/db/8f/61959034484a4a7c527811f4721e75d02d653a35afb0b6054474d8185d4c/charset_normalizer-3.4.7-py3-none-any.whl", hash = "sha256:3dce51d0f5e7951f8bb4900c257dad282f49190fdbebecd4ba99bcc41fef404d", size = 61958, upload-time = "2026-04-02T09:28:37.794Z" },
-]
-
-[[package]]
-name = "click"
-version = "8.3.3"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "colorama", marker = "sys_platform == 'win32'" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/bb/63/f9e1ea081ce35720d8b92acde70daaedace594dc93b693c869e0d5910718/click-8.3.3.tar.gz", hash = "sha256:398329ad4837b2ff7cbe1dd166a4c0f8900c3ca3a218de04466f38f6497f18a2", size = 328061, upload-time = "2026-04-22T15:11:27.506Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/ae/44/c1221527f6a71a01ec6fbad7fa78f1d50dfa02217385cf0fa3eec7087d59/click-8.3.3-py3-none-any.whl", hash = "sha256:a2bf429bb3033c89fa4936ffb35d5cb471e3719e1f3c8a7c3fff0b8314305613", size = 110502, upload-time = "2026-04-22T15:11:25.044Z" },
-]
-
-[[package]]
-name = "colorama"
-version = "0.4.6"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/d8/53/6f443c9a4a8358a93a6792e2acffb9d9d5cb0a5cfd8802644b7b1c9a02e4/colorama-0.4.6.tar.gz", hash = "sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44", size = 27697, upload-time = "2022-10-25T02:36:22.414Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/d1/d6/3965ed04c63042e047cb6a3e6ed1a63a35087b6a609aa3a15ed8ac56c221/colorama-0.4.6-py2.py3-none-any.whl", hash = "sha256:4f1d9991f5acc0ca119f9d443620b77f9d6b33703e51011c16baf57afb285fc6", size = 25335, upload-time = "2022-10-25T02:36:20.889Z" },
-]
-
-[[package]]
-name = "cryptography"
-version = "48.0.0"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "cffi", marker = "platform_python_implementation != 'PyPy'" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/9f/a9/db8f313fdcd85d767d4973515e1db101f9c71f95fced83233de224673757/cryptography-48.0.0.tar.gz", hash = "sha256:5c3932f4436d1cccb036cb0eaef46e6e2db91035166f1ad6505c3c9d5a635920", size = 832984, upload-time = "2026-05-04T22:59:38.133Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/df/3d/01f6dd9190170a5a241e0e98c2d04be3664a9e6f5b9b872cde63aff1c3dd/cryptography-48.0.0-cp311-abi3-macosx_10_9_universal2.whl", hash = "sha256:0c558d2cdffd8f4bbb30fc7134c74d2ca9a476f830bb053074498fbc86f41ed6", size = 8001587, upload-time = "2026-05-04T22:57:36.803Z" },
-    { url = "https://files.pythonhosted.org/packages/b2/6e/e90527eef33f309beb811cf7c982c3aeffcce8e3edb178baa4ca3ae4a6fa/cryptography-48.0.0-cp311-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:f5333311663ea94f75dd408665686aaf426563556bb5283554a3539177e03b8c", size = 4690433, upload-time = "2026-05-04T22:57:40.373Z" },
-    { url = "https://files.pythonhosted.org/packages/90/04/673510ed51ddff56575f306cf1617d80411ee76831ccd3097599140efdfe/cryptography-48.0.0-cp311-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:7995ef305d7165c3f11ae07f2517e5a4f1d5c18da1376a0a9ed496336b69e5f3", size = 4710620, upload-time = "2026-05-04T22:57:42.935Z" },
-    { url = "https://files.pythonhosted.org/packages/14/d5/e9c4ef932c8d800490c34d8bd589d64a31d5890e27ec9e9ad532be893294/cryptography-48.0.0-cp311-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:40ba1f85eaa6959837b1d51c9767e230e14612eea4ef110ee8854ada22da1bf5", size = 4696283, upload-time = "2026-05-04T22:57:45.294Z" },
-    { url = "https://files.pythonhosted.org/packages/0c/29/174b9dfb60b12d59ecfc6cfa04bc88c21b42a54f01b8aae09bb6e51e4c7f/cryptography-48.0.0-cp311-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:369a6348999f94bbd53435c894377b20ab95f25a9065c283570e70150d8abc3c", size = 5296573, upload-time = "2026-05-04T22:57:47.933Z" },
-    { url = "https://files.pythonhosted.org/packages/95/38/0d29a6fd7d0d1373f0c0c88a04ba20e359b257753ac497564cd660fc1d55/cryptography-48.0.0-cp311-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:a0e692c683f4df67815a2d258b324e66f4738bd7a96a218c826dce4f4bd05d8f", size = 4743677, upload-time = "2026-05-04T22:57:50.067Z" },
-    { url = "https://files.pythonhosted.org/packages/30/be/eef653013d5c63b6a490529e0316f9ac14a37602965d4903efed1399f32b/cryptography-48.0.0-cp311-abi3-manylinux_2_31_armv7l.whl", hash = "sha256:18349bbc56f4743c8b12dc32e2bccb2cf83ee8b69a3bba74ef8ae857e26b3d25", size = 4330808, upload-time = "2026-05-04T22:57:52.301Z" },
-    { url = "https://files.pythonhosted.org/packages/84/9e/500463e87abb7a0a0f9f256ec21123ecde0a7b5541a15e840ea54551fd81/cryptography-48.0.0-cp311-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:7e8eac43dfca5c4cccc6dad9a80504436fca53bb9bc3100a2386d730fbe6b602", size = 4695941, upload-time = "2026-05-04T22:57:54.603Z" },
-    { url = "https://files.pythonhosted.org/packages/e3/dc/7303087450c2ec9e7fbb750e17c2abfbc658f23cbd0e54009509b7cc4091/cryptography-48.0.0-cp311-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:9ccdac7d40688ecb5a3b4a604b8a88c8002e3442d6c60aead1db2a89a041560c", size = 5252579, upload-time = "2026-05-04T22:57:57.207Z" },
-    { url = "https://files.pythonhosted.org/packages/d0/c0/7101d3b7215edcdc90c45da544961fd8ed2d6448f77577460fa75a8443f7/cryptography-48.0.0-cp311-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:bd72e68b06bb1e96913f97dd4901119bc17f39d4586a5adf2d3e47bc2b9d58b5", size = 4743326, upload-time = "2026-05-04T22:57:59.535Z" },
-    { url = "https://files.pythonhosted.org/packages/ac/d8/5b833bad13016f562ab9d063d68199a4bd121d18458e439515601d3357ec/cryptography-48.0.0-cp311-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:59baa2cb386c4f0b9905bd6eb4c2a79a69a128408fd31d32ca4d7102d4156321", size = 4826672, upload-time = "2026-05-04T22:58:01.996Z" },
-    { url = "https://files.pythonhosted.org/packages/98/e1/7074eb8bf3c135558c73fc2bcf0f5633f912e6fb87e868a55c454080ef09/cryptography-48.0.0-cp311-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:9249e3cd978541d665967ac2cb2787fd6a62bddf1e75b3e347a594d7dacf4f74", size = 4972574, upload-time = "2026-05-04T22:58:03.968Z" },
-    { url = "https://files.pythonhosted.org/packages/04/70/e5a1b41d325f797f39427aa44ef8baf0be500065ab6d8e10369d850d4a4f/cryptography-48.0.0-cp311-abi3-win32.whl", hash = "sha256:9c459db21422be75e2809370b829a87eb37f74cd785fc4aa9ea1e5f43b47cda4", size = 3294868, upload-time = "2026-05-04T22:58:06.467Z" },
-    { url = "https://files.pythonhosted.org/packages/f4/ac/8ac51b4a5fc5932eb7ee5c517ba7dc8cd834f0048962b6b352f00f41ebf9/cryptography-48.0.0-cp311-abi3-win_amd64.whl", hash = "sha256:5b012212e08b8dd5edc78ef54da83dd9892fd9105323b3993eff6bea65dc21d7", size = 3817107, upload-time = "2026-05-04T22:58:08.845Z" },
-    { url = "https://files.pythonhosted.org/packages/6b/84/70e3feea9feea87fd7cbe77efb2712ae1e3e6edf10749dc6e95f4e60e455/cryptography-48.0.0-cp314-cp314t-macosx_10_9_universal2.whl", hash = "sha256:3cb07a3ed6431663cd321ea8a000a1314c74211f823e4177fefa2255e057d1ec", size = 7986556, upload-time = "2026-05-04T22:58:11.172Z" },
-    { url = "https://files.pythonhosted.org/packages/89/6e/18e07a618bb5442ba10cf4df16e99c071365528aa570dfcb8c02e25a303b/cryptography-48.0.0-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:8c7378637d7d88016fa6791c159f698b3d3eed28ebf844ac36b9dc04a14dae18", size = 4684776, upload-time = "2026-05-04T22:58:13.712Z" },
-    { url = "https://files.pythonhosted.org/packages/be/6a/4ea3b4c6c6759794d5ee2103c304a5076dc4b19ae1f9fe47dba439e159e9/cryptography-48.0.0-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:cc90c0b39b2e3c65ef52c804b72e3c58f8a04ab2a1871272798e5f9572c17d20", size = 4698121, upload-time = "2026-05-04T22:58:16.448Z" },
-    { url = "https://files.pythonhosted.org/packages/2f/59/6ff6ad6cae03bb887da2a5860b2c9805f8dac969ef01ce563336c49bd1d1/cryptography-48.0.0-cp314-cp314t-manylinux_2_28_aarch64.whl", hash = "sha256:76341972e1eff8b4bea859f09c0d3e64b96ce931b084f9b9b7db8ef364c30eff", size = 4690042, upload-time = "2026-05-04T22:58:18.544Z" },
-    { url = "https://files.pythonhosted.org/packages/ca/b4/fc334ed8cfd705aca282fe4d8f5ae64a8e0f74932e9feecb344610cf6e4d/cryptography-48.0.0-cp314-cp314t-manylinux_2_28_ppc64le.whl", hash = "sha256:55b7718303bf06a5753dcdccf2f3945cf18ad7bffde41b61226e4db31ab89a9c", size = 5282526, upload-time = "2026-05-04T22:58:20.75Z" },
-    { url = "https://files.pythonhosted.org/packages/11/08/9f8c5386cc4cd90d8255c7cdd0f5baf459a08502a09de30dc51f553d38dc/cryptography-48.0.0-cp314-cp314t-manylinux_2_28_x86_64.whl", hash = "sha256:a64697c641c7b1b2178e573cbc31c7c6684cd56883a478d75143dbb7118036db", size = 4733116, upload-time = "2026-05-04T22:58:23.627Z" },
-    { url = "https://files.pythonhosted.org/packages/b8/77/99307d7574045699f8805aa500fa0fb83422d115b5400a064ddd306d7750/cryptography-48.0.0-cp314-cp314t-manylinux_2_31_armv7l.whl", hash = "sha256:561215ea3879cb1cbbf272867e2efda62476f240fb58c64de6b393ae19246741", size = 4316030, upload-time = "2026-05-04T22:58:25.581Z" },
-    { url = "https://files.pythonhosted.org/packages/fd/36/a608b98337af3cb2aff4818e406649d30572b7031918b04c87d979495348/cryptography-48.0.0-cp314-cp314t-manylinux_2_34_aarch64.whl", hash = "sha256:ad64688338ed4bc1a6618076ba75fd7194a5f1797ac60b47afe926285adb3166", size = 4689640, upload-time = "2026-05-04T22:58:27.747Z" },
-    { url = "https://files.pythonhosted.org/packages/dd/a6/825010a291b4438aecc1f568bc428189fc1175515223632477c07dc0a6df/cryptography-48.0.0-cp314-cp314t-manylinux_2_34_ppc64le.whl", hash = "sha256:906cbf0670286c6e0044156bc7d4af9cbb0ef6db9f73e52c3ec56ba6bdde5336", size = 5237657, upload-time = "2026-05-04T22:58:29.848Z" },
-    { url = "https://files.pythonhosted.org/packages/b9/09/4e76a09b4caa29aad535ddc806f5d4c5d01885bd978bd984fbc6ca032cae/cryptography-48.0.0-cp314-cp314t-manylinux_2_34_x86_64.whl", hash = "sha256:ea8990436d914540a40ab24b6a77c0969695ed52f4a4874c5137ccf7045a7057", size = 4732362, upload-time = "2026-05-04T22:58:32.009Z" },
-    { url = "https://files.pythonhosted.org/packages/18/78/444fa04a77d0cb95f417dda20d450e13c56ba8e5220fc892a1658f44f882/cryptography-48.0.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:c18684a7f0cc9a3cb60328f496b8e3372def7c5d2df39ac267878b05565aaaae", size = 4819580, upload-time = "2026-05-04T22:58:34.254Z" },
-    { url = "https://files.pythonhosted.org/packages/38/85/ea67067c70a1fd4be2c63d35eeed82658023021affccc7b17705f8527dd2/cryptography-48.0.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:9be5aafa5736574f8f15f262adc81b2a9869e2cfe9014d52a44633905b40d52c", size = 4963283, upload-time = "2026-05-04T22:58:36.376Z" },
-    { url = "https://files.pythonhosted.org/packages/75/54/cc6d0f3deac3e81c7f847e8a189a12b6cdd65059b43dad25d4316abd849a/cryptography-48.0.0-cp314-cp314t-win32.whl", hash = "sha256:c17dfe85494deaeddc5ce251aebd1d60bbe6afc8b62071bb0b469431a000124f", size = 3270954, upload-time = "2026-05-04T22:58:38.791Z" },
-    { url = "https://files.pythonhosted.org/packages/49/67/cc947e288c0758a4e5473d1dcb743037ab7785541265a969240b8885441a/cryptography-48.0.0-cp314-cp314t-win_amd64.whl", hash = "sha256:27241b1dc9962e056062a8eef1991d02c3a24569c95975bd2322a8a52c6e5e12", size = 3797313, upload-time = "2026-05-04T22:58:40.746Z" },
-    { url = "https://files.pythonhosted.org/packages/f2/63/61d4a4e1c6b6bab6ce1e213cd36a24c415d90e76d78c5eb8577c5541d2e8/cryptography-48.0.0-cp39-abi3-macosx_10_9_universal2.whl", hash = "sha256:58d00498e8933e4a194f3076aee1b4a97dfec1a6da444535755822fe5d8b0b86", size = 7983482, upload-time = "2026-05-04T22:58:43.769Z" },
-    { url = "https://files.pythonhosted.org/packages/d5/ac/f5b5995b87770c693e2596559ffafe195b4033a57f14a82268a2842953f3/cryptography-48.0.0-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:614d0949f4790582d2cc25553abd09dd723025f0c0e7c67376a1d77196743d6e", size = 4683266, upload-time = "2026-05-04T22:58:46.064Z" },
-    { url = "https://files.pythonhosted.org/packages/ec/c6/8b14f67e18338fbc4adb76f66c001f5c3610b3e2d1837f268f47a347dbbb/cryptography-48.0.0-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:7ce4bfae76319a532a2dc68f82cc32f5676ee792a983187dac07183690e5c66f", size = 4696228, upload-time = "2026-05-04T22:58:48.22Z" },
-    { url = "https://files.pythonhosted.org/packages/ea/73/f808fbae9514bd91b47875b003f13e284c8c6bdfd904b7944e803937eec1/cryptography-48.0.0-cp39-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:2eb992bbd4661238c5a397594c83f5b4dc2bc5b848c365c8f991b6780efcc5c7", size = 4689097, upload-time = "2026-05-04T22:58:50.9Z" },
-    { url = "https://files.pythonhosted.org/packages/93/01/d86632d7d28db8ae83221995752eeb6639ffb374c2d22955648cf8d52797/cryptography-48.0.0-cp39-abi3-manylinux_2_28_ppc64le.whl", hash = "sha256:22a5cb272895dce158b2cacdfdc3debd299019659f42947dbdac6f32d68fe832", size = 5283582, upload-time = "2026-05-04T22:58:53.017Z" },
-    { url = "https://files.pythonhosted.org/packages/02/e1/50edc7a50334807cc4791fc4a0ce7468b4a1416d9138eab358bfc9a3d70b/cryptography-48.0.0-cp39-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:2b4d59804e8408e2fea7d1fbaf218e5ec984325221db76e6a241a9abd6cdd95c", size = 4730479, upload-time = "2026-05-04T22:58:55.611Z" },
-    { url = "https://files.pythonhosted.org/packages/6f/af/99a582b1b1641ff5911ac559beb45097cf79efd4ead4657f578ef1af2d47/cryptography-48.0.0-cp39-abi3-manylinux_2_31_armv7l.whl", hash = "sha256:984a20b0f62a26f48a3396c72e4bc34c66e356d356bf370053066b3b6d54634a", size = 4326481, upload-time = "2026-05-04T22:58:57.607Z" },
-    { url = "https://files.pythonhosted.org/packages/90/ee/89aa26a06ef0a7d7611788ffd571a7c50e368cc6a4d5eef8b4884e866edb/cryptography-48.0.0-cp39-abi3-manylinux_2_34_aarch64.whl", hash = "sha256:5a5ed8fde7a1d09376ca0b40e68cd59c69fe23b1f9768bd5824f54681626032a", size = 4688713, upload-time = "2026-05-04T22:59:00.077Z" },
-    { url = "https://files.pythonhosted.org/packages/70/ba/bcb1b0bb7a33d4c7c0c4d4c7874b4a62ae4f56113a5f4baefa362dfb1f0f/cryptography-48.0.0-cp39-abi3-manylinux_2_34_ppc64le.whl", hash = "sha256:8cd666227ef7af430aa5914a9910e0ddd703e75f039cef0825cd0da71b6b711a", size = 5238165, upload-time = "2026-05-04T22:59:02.317Z" },
-    { url = "https://files.pythonhosted.org/packages/c9/70/ca4003b1ce5ca3dc3186ada51908c8a9b9ff7d5cab83cc0d43ee14ec144f/cryptography-48.0.0-cp39-abi3-manylinux_2_34_x86_64.whl", hash = "sha256:9071196d81abc88b3516ac8cdfad32e2b66dd4a5393a8e68a961e9161ddc6239", size = 4729947, upload-time = "2026-05-04T22:59:05.255Z" },
-    { url = "https://files.pythonhosted.org/packages/44/a0/4ec7cf774207905aef1a8d11c3750d5a1db805eb380ee4e16df317870128/cryptography-48.0.0-cp39-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:1e2d54c8be6152856a36f0882ab231e70f8ec7f14e93cf87db8a2ed056bf160c", size = 4822059, upload-time = "2026-05-04T22:59:07.802Z" },
-    { url = "https://files.pythonhosted.org/packages/1e/75/a2e55f99c16fcac7b5d6c1eb19ad8e00799854d6be5ca845f9259eae1681/cryptography-48.0.0-cp39-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:a5da777e32ffed6f85a7b2b3f7c5cbc88c146bfcd0a1d7baf5fcc6c52ee35dd4", size = 4960575, upload-time = "2026-05-04T22:59:09.851Z" },
-    { url = "https://files.pythonhosted.org/packages/b8/23/6e6f32143ab5d8b36ca848a502c4bcd477ae75b9e1677e3530d669062578/cryptography-48.0.0-cp39-abi3-win32.whl", hash = "sha256:77a2ccbbe917f6710e05ba9adaa25fb5075620bf3ea6fb751997875aff4ae4bd", size = 3279117, upload-time = "2026-05-04T22:59:12.019Z" },
-    { url = "https://files.pythonhosted.org/packages/9d/9a/0fea98a70cf1749d41d738836f6349d97945f7c89433a259a6c2642eefeb/cryptography-48.0.0-cp39-abi3-win_amd64.whl", hash = "sha256:16cd65b9330583e4619939b3a3843eec1e6e789744bb01e7c7e2e62e33c239c8", size = 3792100, upload-time = "2026-05-04T22:59:14.884Z" },
-]
-
-[[package]]
-name = "distro"
-version = "1.9.0"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/fc/f8/98eea607f65de6527f8a2e8885fc8015d3e6f5775df186e443e0964a11c3/distro-1.9.0.tar.gz", hash = "sha256:2fa77c6fd8940f116ee1d6b94a2f90b13b5ea8d019b98bc8bafdcabcdd9bdbed", size = 60722, upload-time = "2023-12-24T09:54:32.31Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/12/b3/231ffd4ab1fc9d679809f356cebee130ac7daa00d6d6f3206dd4fd137e9e/distro-1.9.0-py3-none-any.whl", hash = "sha256:7bffd925d65168f85027d8da9af6bddab658135b840670a223589bc0c8ef02b2", size = 20277, upload-time = "2023-12-24T09:54:30.421Z" },
-]
-
-[[package]]
-name = "h11"
-version = "0.16.0"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/01/ee/02a2c011bdab74c6fb3c75474d40b3052059d95df7e73351460c8588d963/h11-0.16.0.tar.gz", hash = "sha256:4e35b956cf45792e4caa5885e69fba00bdbc6ffafbfa020300e549b208ee5ff1", size = 101250, upload-time = "2025-04-24T03:35:25.427Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/04/4b/29cac41a4d98d144bf5f6d33995617b185d14b22401f75ca86f384e87ff1/h11-0.16.0-py3-none-any.whl", hash = "sha256:63cf8bbe7522de3bf65932fda1d9c2772064ffb3dae62d55932da54b31cb6c86", size = 37515, upload-time = "2025-04-24T03:35:24.344Z" },
-]
-
-[[package]]
-name = "httpcore"
-version = "1.0.9"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "certifi" },
-    { name = "h11" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/06/94/82699a10bca87a5556c9c59b5963f2d039dbd239f25bc2a63907a05a14cb/httpcore-1.0.9.tar.gz", hash = "sha256:6e34463af53fd2ab5d807f399a9b45ea31c3dfa2276f15a2c3f00afff6e176e8", size = 85484, upload-time = "2025-04-24T22:06:22.219Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/7e/f5/f66802a942d491edb555dd61e3a9961140fd64c90bce1eafd741609d334d/httpcore-1.0.9-py3-none-any.whl", hash = "sha256:2d400746a40668fc9dec9810239072b40b4484b640a8c38fd654a024c7a1bf55", size = 78784, upload-time = "2025-04-24T22:06:20.566Z" },
-]
-
-[[package]]
-name = "httpx"
-version = "0.28.1"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "anyio" },
-    { name = "certifi" },
-    { name = "httpcore" },
-    { name = "idna" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/b1/df/48c586a5fe32a0f01324ee087459e112ebb7224f646c0b5023f5e79e9956/httpx-0.28.1.tar.gz", hash = "sha256:75e98c5f16b0f35b567856f597f06ff2270a374470a5c2392242528e3e3e42fc", size = 141406, upload-time = "2024-12-06T15:37:23.222Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/2a/39/e50c7c3a983047577ee07d2a9e53faf5a69493943ec3f6a384bdc792deb2/httpx-0.28.1-py3-none-any.whl", hash = "sha256:d909fcccc110f8c7faf814ca82a9a4d816bc5a6dbfea25d6591d6985b8ba59ad", size = 73517, upload-time = "2024-12-06T15:37:21.509Z" },
-]
-
-[[package]]
-name = "httpx-sse"
-version = "0.4.3"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/0f/4c/751061ffa58615a32c31b2d82e8482be8dd4a89154f003147acee90f2be9/httpx_sse-0.4.3.tar.gz", hash = "sha256:9b1ed0127459a66014aec3c56bebd93da3c1bc8bb6618c8082039a44889a755d", size = 15943, upload-time = "2025-10-10T21:48:22.271Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/d2/fd/6668e5aec43ab844de6fc74927e155a3b37bf40d7c3790e49fc0406b6578/httpx_sse-0.4.3-py3-none-any.whl", hash = "sha256:0ac1c9fe3c0afad2e0ebb25a934a59f4c7823b60792691f779fad2c5568830fc", size = 8960, upload-time = "2025-10-10T21:48:21.158Z" },
-]
-
-[[package]]
-name = "idna"
-version = "3.14"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/05/b1/efac073e0c297ecf2fb33c346989a529d4e19164f1759102dee5953ee17e/idna-3.14.tar.gz", hash = "sha256:466d810d7a2cc1022bea9b037c39728d51ae7dad40d480fc9b7d7ecf98ba8ee3", size = 198272, upload-time = "2026-05-10T20:32:15.935Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/6c/3c/3f62dee257eb3d6b2c1ef2a09d36d9793c7111156a73b5654d2c2305e5ce/idna-3.14-py3-none-any.whl", hash = "sha256:e677eaf072e290f7b725f9acf0b3a2bd55f9fd6f7c70abe5f0e34823d0accf69", size = 72184, upload-time = "2026-05-10T20:32:14.295Z" },
-]
-
-[[package]]
-name = "jiter"
-version = "0.14.0"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/6e/c1/0cddc6eb17d4c53a99840953f95dd3accdc5cfc7a337b0e9b26476276be9/jiter-0.14.0.tar.gz", hash = "sha256:e8a39e66dac7153cf3f964a12aad515afa8d74938ec5cc0018adcdae5367c79e", size = 165725, upload-time = "2026-04-10T14:28:42.01Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/5a/68/7390a418f10897da93b158f2d5a8bd0bcd73a0f9ec3bb36917085bb759ef/jiter-0.14.0-cp312-cp312-macosx_10_12_x86_64.whl", hash = "sha256:2fb2ce3a7bc331256dfb14cefc34832366bb28a9aca81deaf43bbf2a5659e607", size = 316295, upload-time = "2026-04-10T14:26:24.887Z" },
-    { url = "https://files.pythonhosted.org/packages/60/a0/5854ac00ff63551c52c6c89534ec6aba4b93474e7924d64e860b1c94165b/jiter-0.14.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:5252a7ca23785cef5d02d4ece6077a1b556a410c591b379f82091c3001e14844", size = 315898, upload-time = "2026-04-10T14:26:26.601Z" },
-    { url = "https://files.pythonhosted.org/packages/41/a1/4f44832650a16b18e8391f1bf1d6ca4909bc738351826bcc198bba4357f4/jiter-0.14.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:c409578cbd77c338975670ada777add4efd53379667edf0aceea730cabede6fb", size = 343730, upload-time = "2026-04-10T14:26:28.326Z" },
-    { url = "https://files.pythonhosted.org/packages/48/64/a329e9d469f86307203594b1707e11ae51c3348d03bfd514a5f997870012/jiter-0.14.0-cp312-cp312-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:7ede4331a1899d604463369c730dbb961ffdc5312bc7f16c41c2896415b1304a", size = 370102, upload-time = "2026-04-10T14:26:30.089Z" },
-    { url = "https://files.pythonhosted.org/packages/94/c1/5e3dfc59635aa4d4c7bd20a820ac1d09b8ed851568356802cf1c08edb3cf/jiter-0.14.0-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:92cd8b6025981a041f5310430310b55b25ca593972c16407af8837d3d7d2ca01", size = 461335, upload-time = "2026-04-10T14:26:31.911Z" },
-    { url = "https://files.pythonhosted.org/packages/e3/1b/dd157009dbc058f7b00108f545ccb72a2d56461395c4fc7b9cfdccb00af4/jiter-0.14.0-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:351bf6eda4e3a7ceb876377840c702e9a3e4ecc4624dbfb2d6463c67ae52637d", size = 378536, upload-time = "2026-04-10T14:26:33.595Z" },
-    { url = "https://files.pythonhosted.org/packages/91/78/256013667b7c10b8834f8e6e54cd3e562d4c6e34227a1596addccc05e38c/jiter-0.14.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:c1dcfbeb93d9ecd9ca128bbf8910120367777973fa193fb9a39c31237d8df165", size = 353859, upload-time = "2026-04-10T14:26:35.098Z" },
-    { url = "https://files.pythonhosted.org/packages/de/d9/137d65ade9093a409fe80955ce60b12bb753722c986467aeda47faf450ad/jiter-0.14.0-cp312-cp312-manylinux_2_31_riscv64.whl", hash = "sha256:ae039aaef8de3f8157ecc1fdd4d85043ac4f57538c245a0afaecb8321ec951c3", size = 357626, upload-time = "2026-04-10T14:26:36.685Z" },
-    { url = "https://files.pythonhosted.org/packages/2e/48/76750835b87029342727c1a268bea8878ab988caf81ee4e7b880900eeb5a/jiter-0.14.0-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:7d9d51eb96c82a9652933bd769fe6de66877d6eb2b2440e281f2938c51b5643e", size = 393172, upload-time = "2026-04-10T14:26:38.097Z" },
-    { url = "https://files.pythonhosted.org/packages/a6/60/456c4e81d5c8045279aefe60e9e483be08793828800a4e64add8fdde7f2a/jiter-0.14.0-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:d824ca4148b705970bf4e120924a212fdfca9859a73e42bd7889a63a4ea6bb98", size = 520300, upload-time = "2026-04-10T14:26:39.532Z" },
-    { url = "https://files.pythonhosted.org/packages/a8/9f/2020e0984c235f678dced38fe4eec3058cf528e6af36ebf969b410305941/jiter-0.14.0-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:ff3a6465b3a0f54b1a430f45c3c0ba7d61ceb45cbc3e33f9e1a7f638d690baf3", size = 553059, upload-time = "2026-04-10T14:26:40.991Z" },
-    { url = "https://files.pythonhosted.org/packages/ef/32/e2d298e1a22a4bbe6062136d1c7192db7dba003a6975e51d9a9eecabc4c2/jiter-0.14.0-cp312-cp312-win32.whl", hash = "sha256:5dec7c0a3e98d2a3f8a2e67382d0d7c3ac60c69103a4b271da889b4e8bb1e129", size = 206030, upload-time = "2026-04-10T14:26:42.517Z" },
-    { url = "https://files.pythonhosted.org/packages/36/ac/96369141b3d8a4a8e4590e983085efe1c436f35c0cda940dd76d942e3e40/jiter-0.14.0-cp312-cp312-win_amd64.whl", hash = "sha256:fc7e37b4b8bc7e80a63ad6cfa5fc11fab27dbfea4cc4ae644b1ab3f273dc348f", size = 201603, upload-time = "2026-04-10T14:26:44.328Z" },
-    { url = "https://files.pythonhosted.org/packages/01/c3/75d847f264647017d7e3052bbcc8b1e24b95fa139c320c5f5066fa7a0bdd/jiter-0.14.0-cp312-cp312-win_arm64.whl", hash = "sha256:ee4a72f12847ef29b072aee9ad5474041ab2924106bdca9fcf5d7d965853e057", size = 191525, upload-time = "2026-04-10T14:26:46Z" },
-    { url = "https://files.pythonhosted.org/packages/97/2a/09f70020898507a89279659a1afe3364d57fc1b2c89949081975d135f6f5/jiter-0.14.0-cp313-cp313-macosx_10_12_x86_64.whl", hash = "sha256:af72f204cf4d44258e5b4c1745130ac45ddab0e71a06333b01de660ab4187a94", size = 315502, upload-time = "2026-04-10T14:26:47.697Z" },
-    { url = "https://files.pythonhosted.org/packages/d6/be/080c96a45cd74f9fce5db4fd68510b88087fb37ffe2541ff73c12db92535/jiter-0.14.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:4b77da71f6e819be5fbcec11a453fde5b1d0267ef6ed487e2a392fd8e14e4e3a", size = 314870, upload-time = "2026-04-10T14:26:49.149Z" },
-    { url = "https://files.pythonhosted.org/packages/7d/5e/2d0fee155826a968a832cc32438de5e2a193292c8721ca70d0b53e58245b/jiter-0.14.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:77f4ea612fe8b84b8b04e51d0e78029ecf3466348e25973f953de6e6a59aa4c1", size = 343406, upload-time = "2026-04-10T14:26:50.762Z" },
-    { url = "https://files.pythonhosted.org/packages/70/af/bf9ee0d3a4f8dc0d679fc1337f874fe60cdbf841ebbb304b374e1c9aaceb/jiter-0.14.0-cp313-cp313-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:62fe2451f8fcc0240261e6a4df18ecbcd58327857e61e625b2393ea3b468aac9", size = 369415, upload-time = "2026-04-10T14:26:52.188Z" },
-    { url = "https://files.pythonhosted.org/packages/0f/83/8e8561eadba31f4d3948a5b712fb0447ec71c3560b57a855449e7b8ddc98/jiter-0.14.0-cp313-cp313-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:6112f26f5afc75bcb475787d29da3aa92f9d09c7858f632f4be6ffe607be82e9", size = 461456, upload-time = "2026-04-10T14:26:53.611Z" },
-    { url = "https://files.pythonhosted.org/packages/f6/c9/c5299e826a5fe6108d172b344033f61c69b1bb979dd8d9ddd4278a160971/jiter-0.14.0-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:215a6cb8fb7dc702aa35d475cc00ddc7f970e5c0b1417fb4b4ac5d82fa2a29db", size = 378488, upload-time = "2026-04-10T14:26:55.211Z" },
-    { url = "https://files.pythonhosted.org/packages/5d/37/c16d9d15c0a471b8644b1abe3c82668092a707d9bedcf076f24ff2e380cd/jiter-0.14.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:fc4ab96a30fb3cb2c7e0cd33f7616c8860da5f5674438988a54ac717caccdbaa", size = 353242, upload-time = "2026-04-10T14:26:56.705Z" },
-    { url = "https://files.pythonhosted.org/packages/58/ea/8050cb0dc654e728e1bfacbc0c640772f2181af5dedd13ae70145743a439/jiter-0.14.0-cp313-cp313-manylinux_2_31_riscv64.whl", hash = "sha256:3a99c1387b1f2928f799a9de899193484d66206a50e98233b6b088a7f0c1edb2", size = 356823, upload-time = "2026-04-10T14:26:58.281Z" },
-    { url = "https://files.pythonhosted.org/packages/b0/3b/cf71506d270e5f84d97326bf220e47aed9b95e9a4a060758fb07772170ab/jiter-0.14.0-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:ab18d11074485438695f8d34a1b6da61db9754248f96d51341956607a8f39985", size = 392564, upload-time = "2026-04-10T14:27:00.018Z" },
-    { url = "https://files.pythonhosted.org/packages/b0/cc/8c6c74a3efb5bd671bfd14f51e8a73375464ca914b1551bc3b40e26ac2c9/jiter-0.14.0-cp313-cp313-musllinux_1_1_aarch64.whl", hash = "sha256:801028dcfc26ac0895e4964cbc0fd62c73be9fd4a7d7b1aaf6e5790033a719b7", size = 520322, upload-time = "2026-04-10T14:27:01.664Z" },
-    { url = "https://files.pythonhosted.org/packages/41/24/68d7b883ec959884ddf00d019b2e0e82ba81b167e1253684fa90519ce33c/jiter-0.14.0-cp313-cp313-musllinux_1_1_x86_64.whl", hash = "sha256:ad425b087aafb4a1c7e1e98a279200743b9aaf30c3e0ba723aec93f061bd9bc8", size = 552619, upload-time = "2026-04-10T14:27:03.316Z" },
-    { url = "https://files.pythonhosted.org/packages/b6/89/b1a0985223bbf3150ff9e8f46f98fc9360c1de94f48abe271bbe1b465682/jiter-0.14.0-cp313-cp313-win32.whl", hash = "sha256:882bcb9b334318e233950b8be366fe5f92c86b66a7e449e76975dfd6d776a01f", size = 205699, upload-time = "2026-04-10T14:27:04.662Z" },
-    { url = "https://files.pythonhosted.org/packages/4c/19/3f339a5a7f14a11730e67f6be34f9d5105751d547b615ef593fa122a5ded/jiter-0.14.0-cp313-cp313-win_amd64.whl", hash = "sha256:9b8c571a5dba09b98bd3462b5a53f27209a5cbbe85670391692ede71974e979f", size = 201323, upload-time = "2026-04-10T14:27:06.139Z" },
-    { url = "https://files.pythonhosted.org/packages/50/56/752dd89c84be0e022a8ea3720bcfa0a8431db79a962578544812ce061739/jiter-0.14.0-cp313-cp313-win_arm64.whl", hash = "sha256:34f19dcc35cb1abe7c369b3756babf8c7f04595c0807a848df8f26ef8298ef92", size = 191099, upload-time = "2026-04-10T14:27:07.564Z" },
-    { url = "https://files.pythonhosted.org/packages/91/28/292916f354f25a1fe8cf2c918d1415c699a4a659ae00be0430e1c5d9ffea/jiter-0.14.0-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:e89bcd7d426a75bb4952c696b267075790d854a07aad4c9894551a82c5b574ab", size = 320880, upload-time = "2026-04-10T14:27:09.326Z" },
-    { url = "https://files.pythonhosted.org/packages/ad/c7/b002a7d8b8957ac3d469bd59c18ef4b1595a5216ae0de639a287b9816023/jiter-0.14.0-cp313-cp313t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:7b25beaa0d4447ea8c7ae0c18c688905d34840d7d0b937f2f7bdd52162c98a40", size = 346563, upload-time = "2026-04-10T14:27:11.287Z" },
-    { url = "https://files.pythonhosted.org/packages/f9/3b/f8d07580d8706021d255a6356b8fab13ee4c869412995550ce6ed4ddf97d/jiter-0.14.0-cp313-cp313t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:651a8758dd413c51e3b7f6557cdc6921faf70b14106f45f969f091f5cda990ea", size = 357928, upload-time = "2026-04-10T14:27:12.729Z" },
-    { url = "https://files.pythonhosted.org/packages/47/5b/ac1a974da29e35507230383110ffec59998b290a8732585d04e19a9eb5ba/jiter-0.14.0-cp313-cp313t-win_amd64.whl", hash = "sha256:e1a7eead856a5038a8d291f1447176ab0b525c77a279a058121b5fccee257f6f", size = 203519, upload-time = "2026-04-10T14:27:14.125Z" },
-    { url = "https://files.pythonhosted.org/packages/96/6d/9fc8433d667d2454271378a79747d8c76c10b51b482b454e6190e511f244/jiter-0.14.0-cp313-cp313t-win_arm64.whl", hash = "sha256:2e692633a12cda97e352fdcd1c4acc971b1c28707e1e33aeef782b0cbf051975", size = 190113, upload-time = "2026-04-10T14:27:16.638Z" },
-    { url = "https://files.pythonhosted.org/packages/4f/1e/354ed92461b165bd581f9ef5150971a572c873ec3b68a916d5aa91da3cc2/jiter-0.14.0-cp314-cp314-macosx_10_12_x86_64.whl", hash = "sha256:6f396837fc7577871ca8c12edaf239ed9ccef3bbe39904ae9b8b63ce0a48b140", size = 315277, upload-time = "2026-04-10T14:27:18.109Z" },
-    { url = "https://files.pythonhosted.org/packages/a6/95/8c7c7028aa8636ac21b7a55faef3e34215e6ed0cbf5ae58258427f621aa3/jiter-0.14.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:a4d50ea3d8ba4176f79754333bd35f1bbcd28e91adc13eb9b7ca91bc52a6cef9", size = 315923, upload-time = "2026-04-10T14:27:19.603Z" },
-    { url = "https://files.pythonhosted.org/packages/47/40/e2a852a44c4a089f2681a16611b7ce113224a80fd8504c46d78491b47220/jiter-0.14.0-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ce17f8a050447d1b4153bda4fb7d26e6a9e74eb4f4a41913f30934c5075bf615", size = 344943, upload-time = "2026-04-10T14:27:21.262Z" },
-    { url = "https://files.pythonhosted.org/packages/fc/1f/670f92adee1e9895eac41e8a4d623b6da68c4d46249d8b556b60b63f949e/jiter-0.14.0-cp314-cp314-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:f4f1c4b125e1652aefbc2e2c1617b60a160ab789d180e3d423c41439e5f32850", size = 369725, upload-time = "2026-04-10T14:27:22.766Z" },
-    { url = "https://files.pythonhosted.org/packages/01/2f/541c9ba567d05de1c4874a0f8f8c5e3fd78e2b874266623da9a775cf46e0/jiter-0.14.0-cp314-cp314-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:be808176a6a3a14321d18c603f2d40741858a7c4fc982f83232842689fe86dd9", size = 461210, upload-time = "2026-04-10T14:27:24.315Z" },
-    { url = "https://files.pythonhosted.org/packages/ce/a9/c31cbec09627e0d5de7aeaec7690dba03e090caa808fefd8133137cf45bc/jiter-0.14.0-cp314-cp314-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:26679d58ba816f88c3849306dd58cb863a90a1cf352cdd4ef67e30ccf8a77994", size = 380002, upload-time = "2026-04-10T14:27:26.155Z" },
-    { url = "https://files.pythonhosted.org/packages/50/02/3c05c1666c41904a2f607475a73e7a4763d1cbde2d18229c4f85b22dc253/jiter-0.14.0-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:80381f5a19af8fa9aef743f080e34f6b25ebd89656475f8cf0470ec6157052aa", size = 354678, upload-time = "2026-04-10T14:27:27.701Z" },
-    { url = "https://files.pythonhosted.org/packages/7d/97/e15b33545c2b13518f560d695f974b9891b311641bdcf178d63177e8801e/jiter-0.14.0-cp314-cp314-manylinux_2_31_riscv64.whl", hash = "sha256:004df5fdb8ecbd6d99f3227df18ba1a259254c4359736a2e6f036c944e02d7c5", size = 358920, upload-time = "2026-04-10T14:27:29.256Z" },
-    { url = "https://files.pythonhosted.org/packages/ad/d2/8b1461def6b96ba44530df20d07ef7a1c7da22f3f9bf1727e2d611077bf1/jiter-0.14.0-cp314-cp314-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:cff5708f7ed0fa098f2b53446c6fa74c48469118e5cd7497b4f1cd569ab06928", size = 394512, upload-time = "2026-04-10T14:27:31.344Z" },
-    { url = "https://files.pythonhosted.org/packages/e3/88/837566dd6ed6e452e8d3205355afd484ce44b2533edfa4ed73a298ea893e/jiter-0.14.0-cp314-cp314-musllinux_1_1_aarch64.whl", hash = "sha256:2492e5f06c36a976d25c7cc347a60e26d5470178d44cde1b9b75e60b4e519f28", size = 521120, upload-time = "2026-04-10T14:27:33.299Z" },
-    { url = "https://files.pythonhosted.org/packages/89/6b/b00b45c4d1b4c031777fe161d620b755b5b02cdade1e316dcb46e4471d63/jiter-0.14.0-cp314-cp314-musllinux_1_1_x86_64.whl", hash = "sha256:7609cfbe3a03d37bfdbf5052012d5a879e72b83168a363deae7b3a26564d57de", size = 553668, upload-time = "2026-04-10T14:27:34.868Z" },
-    { url = "https://files.pythonhosted.org/packages/ad/d8/6fe5b42011d19397433d345716eac16728ac241862a2aac9c91923c7509a/jiter-0.14.0-cp314-cp314-win32.whl", hash = "sha256:7282342d32e357543565286b6450378c3cd402eea333fc1ebe146f1fabb306fc", size = 207001, upload-time = "2026-04-10T14:27:36.455Z" },
-    { url = "https://files.pythonhosted.org/packages/e5/43/5c2e08da1efad5e410f0eaaabeadd954812612c33fbbd8fd5328b489139d/jiter-0.14.0-cp314-cp314-win_amd64.whl", hash = "sha256:bd77945f38866a448e73b0b7637366afa814d4617790ecd88a18ca74377e6c02", size = 202187, upload-time = "2026-04-10T14:27:38Z" },
-    { url = "https://files.pythonhosted.org/packages/aa/1f/6e39ac0b4cdfa23e606af5b245df5f9adaa76f35e0c5096790da430ca506/jiter-0.14.0-cp314-cp314-win_arm64.whl", hash = "sha256:f2d4c61da0821ee42e0cdf5489da60a6d074306313a377c2b35af464955a3611", size = 192257, upload-time = "2026-04-10T14:27:39.504Z" },
-    { url = "https://files.pythonhosted.org/packages/05/57/7dbc0ffbbb5176a27e3518716608aa464aee2e2887dc938f0b900a120449/jiter-0.14.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:1bf7ff85517dd2f20a5750081d2b75083c1b269cf75afc7511bdf1f9548beb3b", size = 323441, upload-time = "2026-04-10T14:27:41.039Z" },
-    { url = "https://files.pythonhosted.org/packages/83/6e/7b3314398d8983f06b557aa21b670511ec72d3b79a68ee5e4d9bff972286/jiter-0.14.0-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:c8ef8791c3e78d6c6b157c6d360fbb5c715bebb8113bc6a9303c5caff012754a", size = 348109, upload-time = "2026-04-10T14:27:42.552Z" },
-    { url = "https://files.pythonhosted.org/packages/ae/4f/8dc674bcd7db6dba566de73c08c763c337058baff1dbeb34567045b27cdc/jiter-0.14.0-cp314-cp314t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:e74663b8b10da1fe0f4e4703fd7980d24ad17174b6bb35d8498d6e3ebce2ae6a", size = 368328, upload-time = "2026-04-10T14:27:44.574Z" },
-    { url = "https://files.pythonhosted.org/packages/3b/5f/188e09a1f20906f98bbdec44ed820e19f4e8eb8aff88b9d1a5a497587ff3/jiter-0.14.0-cp314-cp314t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:1aca29ba52913f78362ec9c2da62f22cdc4c3083313403f90c15460979b84d9b", size = 463301, upload-time = "2026-04-10T14:27:46.717Z" },
-    { url = "https://files.pythonhosted.org/packages/ac/f0/19046ef965ed8f349e8554775bb12ff4352f443fbe12b95d31f575891256/jiter-0.14.0-cp314-cp314t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:8b39b7d87a952b79949af5fef44d2544e58c21a28da7f1bae3ef166455c61746", size = 378891, upload-time = "2026-04-10T14:27:48.32Z" },
-    { url = "https://files.pythonhosted.org/packages/c4/c3/da43bd8431ee175695777ee78cf0e93eacbb47393ff493f18c45231b427d/jiter-0.14.0-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:78d918a68b26e9fab068c2b5453577ef04943ab2807b9a6275df2a812599a310", size = 360749, upload-time = "2026-04-10T14:27:49.88Z" },
-    { url = "https://files.pythonhosted.org/packages/72/26/e054771be889707c6161dbdec9c23d33a9ec70945395d70f07cfea1e9a6f/jiter-0.14.0-cp314-cp314t-manylinux_2_31_riscv64.whl", hash = "sha256:b08997c35aee1201c1a5361466a8fb9162d03ae7bf6568df70b6c859f1e654a4", size = 358526, upload-time = "2026-04-10T14:27:51.504Z" },
-    { url = "https://files.pythonhosted.org/packages/c3/0f/7bea65ea2a6d91f2bf989ff11a18136644392bf2b0497a1fa50934c30a9c/jiter-0.14.0-cp314-cp314t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:260bf7ca20704d58d41f669e5e9fe7fe2fa72901a6b324e79056f5d52e9c9be2", size = 393926, upload-time = "2026-04-10T14:27:53.368Z" },
-    { url = "https://files.pythonhosted.org/packages/3c/a1/b1ff7d70deef61ac0b7c6c2f12d2ace950cdeecb4fdc94500a0926802857/jiter-0.14.0-cp314-cp314t-musllinux_1_1_aarch64.whl", hash = "sha256:37826e3df29e60f30a382f9294348d0238ef127f4b5d7f5f8da78b5b9e050560", size = 521052, upload-time = "2026-04-10T14:27:55.058Z" },
-    { url = "https://files.pythonhosted.org/packages/0b/7b/3b0649983cbaf15eda26a414b5b1982e910c67bd6f7b1b490f3cfc76896a/jiter-0.14.0-cp314-cp314t-musllinux_1_1_x86_64.whl", hash = "sha256:645be49c46f2900937ba0eaf871ad5183c96858c0af74b6becc7f4e367e36e06", size = 553716, upload-time = "2026-04-10T14:27:57.269Z" },
-    { url = "https://files.pythonhosted.org/packages/97/f8/33d78c83bd93ae0c0af05293a6660f88a1977caef39a6d72a84afab94ce0/jiter-0.14.0-cp314-cp314t-win32.whl", hash = "sha256:2f7877ed45118de283786178eceaf877110abacd04fde31efff3940ae9672674", size = 207957, upload-time = "2026-04-10T14:27:59.285Z" },
-    { url = "https://files.pythonhosted.org/packages/d6/ac/2b760516c03e2227826d1f7025d89bf6bf6357a28fe75c2a2800873c50bf/jiter-0.14.0-cp314-cp314t-win_amd64.whl", hash = "sha256:14c0cb10337c49f5eafe8e7364daca5e29a020ea03580b8f8e6c597fed4e1588", size = 204690, upload-time = "2026-04-10T14:28:00.962Z" },
-    { url = "https://files.pythonhosted.org/packages/dc/2e/a44c20c58aeed0355f2d326969a181696aeb551a25195f47563908a815be/jiter-0.14.0-cp314-cp314t-win_arm64.whl", hash = "sha256:5419d4aa2024961da9fe12a9cfe7484996735dca99e8e090b5c88595ef1951ff", size = 191338, upload-time = "2026-04-10T14:28:02.853Z" },
-    { url = "https://files.pythonhosted.org/packages/21/42/9042c3f3019de4adcb8c16591c325ec7255beea9fcd33a42a43f3b0b1000/jiter-0.14.0-graalpy312-graalpy250_312_native-macosx_10_12_x86_64.whl", hash = "sha256:fbd9e482663ca9d005d051330e4d2d8150bb208a209409c10f7e7dfdf7c49da9", size = 308810, upload-time = "2026-04-10T14:28:34.673Z" },
-    { url = "https://files.pythonhosted.org/packages/60/cf/a7e19b308bd86bb04776803b1f01a5f9a287a4c55205f4708827ee487fbf/jiter-0.14.0-graalpy312-graalpy250_312_native-macosx_11_0_arm64.whl", hash = "sha256:33a20d838b91ef376b3a56896d5b04e725c7df5bc4864cc6569cf046a8d73b6d", size = 308443, upload-time = "2026-04-10T14:28:36.658Z" },
-    { url = "https://files.pythonhosted.org/packages/ca/44/e26ede3f0caeff93f222559cb0cc4ca68579f07d009d7b6010c5b586f9b1/jiter-0.14.0-graalpy312-graalpy250_312_native-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:432c4db5255d86a259efde91e55cb4c8d18c0521d844c9e2e7efcce3899fb016", size = 343039, upload-time = "2026-04-10T14:28:38.356Z" },
-    { url = "https://files.pythonhosted.org/packages/da/e9/1f9ada30cef7b05e74bb06f52127e7a724976c225f46adb65c37b1dadfb6/jiter-0.14.0-graalpy312-graalpy250_312_native-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:67f00d94b281174144d6532a04b66a12cb866cbdc47c3af3bfe2973677f9861a", size = 349613, upload-time = "2026-04-10T14:28:40.066Z" },
-]
-
-[[package]]
-name = "jsonschema"
-version = "4.26.0"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "attrs" },
-    { name = "jsonschema-specifications" },
-    { name = "referencing" },
-    { name = "rpds-py" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/b3/fc/e067678238fa451312d4c62bf6e6cf5ec56375422aee02f9cb5f909b3047/jsonschema-4.26.0.tar.gz", hash = "sha256:0c26707e2efad8aa1bfc5b7ce170f3fccc2e4918ff85989ba9ffa9facb2be326", size = 366583, upload-time = "2026-01-07T13:41:07.246Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/69/90/f63fb5873511e014207a475e2bb4e8b2e570d655b00ac19a9a0ca0a385ee/jsonschema-4.26.0-py3-none-any.whl", hash = "sha256:d489f15263b8d200f8387e64b4c3a75f06629559fb73deb8fdfb525f2dab50ce", size = 90630, upload-time = "2026-01-07T13:41:05.306Z" },
-]
-
-[[package]]
-name = "jsonschema-specifications"
-version = "2025.9.1"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "referencing" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/19/74/a633ee74eb36c44aa6d1095e7cc5569bebf04342ee146178e2d36600708b/jsonschema_specifications-2025.9.1.tar.gz", hash = "sha256:b540987f239e745613c7a9176f3edb72b832a4ac465cf02712288397832b5e8d", size = 32855, upload-time = "2025-09-08T01:34:59.186Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/41/45/1a4ed80516f02155c51f51e8cedb3c1902296743db0bbc66608a0db2814f/jsonschema_specifications-2025.9.1-py3-none-any.whl", hash = "sha256:98802fee3a11ee76ecaca44429fda8a41bff98b00a0f2838151b113f210cc6fe", size = 18437, upload-time = "2025-09-08T01:34:57.871Z" },
-]
-
-[[package]]
-name = "markdown-it-py"
-version = "4.2.0"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "mdurl" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/06/ff/7841249c247aa650a76b9ee4bbaeae59370dc8bfd2f6c01f3630c35eb134/markdown_it_py-4.2.0.tar.gz", hash = "sha256:04a21681d6fbb623de53f6f364d352309d4094dd4194040a10fd51833e418d49", size = 82454, upload-time = "2026-05-07T12:08:28.36Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/b3/81/4da04ced5a082363ecfa159c010d200ecbd959ae410c10c0264a38cac0f5/markdown_it_py-4.2.0-py3-none-any.whl", hash = "sha256:9f7ebbcd14fe59494226453aed97c1070d83f8d24b6fc3a3bcf9a38092641c4a", size = 91687, upload-time = "2026-05-07T12:08:27.182Z" },
-]
-
-[[package]]
-name = "mcp"
-version = "1.27.1"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "anyio" },
-    { name = "httpx" },
-    { name = "httpx-sse" },
-    { name = "jsonschema" },
-    { name = "pydantic" },
-    { name = "pydantic-settings" },
-    { name = "pyjwt", extra = ["crypto"] },
-    { name = "python-multipart" },
-    { name = "pywin32", marker = "sys_platform == 'win32'" },
-    { name = "sse-starlette" },
-    { name = "starlette" },
-    { name = "typing-extensions" },
-    { name = "typing-inspection" },
-    { name = "uvicorn", marker = "sys_platform != 'emscripten'" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/38/83/d1efe7c2980d8a3afa476f4e3d42d53dd54c0ab94c27bee5d755b45c8b73/mcp-1.27.1.tar.gz", hash = "sha256:0f47e1820f8f8f941466b39749eb1d1839a04caddca2bc60e9d46e8a99914924", size = 608458, upload-time = "2026-05-08T16:50:12.601Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/fd/73/42d9596facebdb533b7f0b86c1b0364ef350d1f8ba78b1052e8a58b48b65/mcp-1.27.1-py3-none-any.whl", hash = "sha256:1af3c4203b329430fde7a87b4fcb6392a041f5cb851fd68fc674016ab4e7c06f", size = 216260, upload-time = "2026-05-08T16:50:10.547Z" },
-]
-
-[package.optional-dependencies]
-cli = [
-    { name = "python-dotenv" },
-    { name = "typer" },
-]
-
-[[package]]
-name = "mdurl"
-version = "0.1.2"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/d6/54/cfe61301667036ec958cb99bd3efefba235e65cdeb9c84d24a8293ba1d90/mdurl-0.1.2.tar.gz", hash = "sha256:bb413d29f5eea38f31dd4754dd7377d4465116fb207585f97bf925588687c1ba", size = 8729, upload-time = "2022-08-14T12:40:10.846Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/b3/38/89ba8ad64ae25be8de66a6d463314cf1eb366222074cfda9ee839c56a4b4/mdurl-0.1.2-py3-none-any.whl", hash = "sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8", size = 9979, upload-time = "2022-08-14T12:40:09.779Z" },
-]
-
-[[package]]
-name = "openai"
-version = "2.36.0"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "anyio" },
-    { name = "distro" },
-    { name = "httpx" },
-    { name = "jiter" },
-    { name = "pydantic" },
-    { name = "sniffio" },
-    { name = "tqdm" },
-    { name = "typing-extensions" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/f4/a1/4d5e84cf51720fc1526cc49e10ac1961abcccb55b0efb3d970db1e9a2728/openai-2.36.0.tar.gz", hash = "sha256:139dea0edd2f1b30c33d46ae1a6929e03906254140318e4608e98fe8c566f2e7", size = 753003, upload-time = "2026-05-07T17:33:17.075Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/9d/1c/5d43735b2553baae2a5e899dcbcd0670a86930d993184d72ca909bf11c9b/openai-2.36.0-py3-none-any.whl", hash = "sha256:143f6194b548dbc2c921af1f1b03b9f14c85fed8a75b5b516f5bcc11a2a50c63", size = 1302361, upload-time = "2026-05-07T17:33:15.063Z" },
-]
-
-[[package]]
-name = "pycparser"
-version = "3.0"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/1b/7d/92392ff7815c21062bea51aa7b87d45576f649f16458d78b7cf94b9ab2e6/pycparser-3.0.tar.gz", hash = "sha256:600f49d217304a5902ac3c37e1281c9fe94e4d0489de643a9504c5cdfdfc6b29", size = 103492, upload-time = "2026-01-21T14:26:51.89Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/0c/c3/44f3fbbfa403ea2a7c779186dc20772604442dde72947e7d01069cbe98e3/pycparser-3.0-py3-none-any.whl", hash = "sha256:b727414169a36b7d524c1c3e31839a521725078d7b2ff038656844266160a992", size = 48172, upload-time = "2026-01-21T14:26:50.693Z" },
-]
-
-[[package]]
-name = "pydantic"
-version = "2.13.4"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "annotated-types" },
-    { name = "pydantic-core" },
-    { name = "typing-extensions" },
-    { name = "typing-inspection" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/18/a5/b60d21ac674192f8ab0ba4e9fd860690f9b4a6e51ca5df118733b487d8d6/pydantic-2.13.4.tar.gz", hash = "sha256:c40756b57adaa8b1efeeced5c196f3f3b7c435f90e84ea7f443901bec8099ef6", size = 844775, upload-time = "2026-05-06T13:43:05.343Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/fd/7b/122376b1fd3c62c1ed9dc80c931ace4844b3c55407b6fb2d199377c9736f/pydantic-2.13.4-py3-none-any.whl", hash = "sha256:45a282cde31d808236fd7ea9d919b128653c8b38b393d1c4ab335c62924d9aba", size = 472262, upload-time = "2026-05-06T13:43:02.641Z" },
-]
-
-[[package]]
-name = "pydantic-core"
-version = "2.46.4"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "typing-extensions" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/9d/56/921726b776ace8d8f5db44c4ef961006580d91dc52b803c489fafd1aa249/pydantic_core-2.46.4.tar.gz", hash = "sha256:62f875393d7f270851f20523dd2e29f082bcc82292d66db2b64ea71f64b6e1c1", size = 471464, upload-time = "2026-05-06T13:37:06.98Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/ce/8c/af022f0af448d7747c5154288d46b5f2bc5f17366eaa0e23e9aa04d59f3b/pydantic_core-2.46.4-cp312-cp312-macosx_10_12_x86_64.whl", hash = "sha256:3245406455a5d98187ec35530fd772b1d799b26667980872c8d4614991e2c4a2", size = 2106158, upload-time = "2026-05-06T13:38:57.215Z" },
-    { url = "https://files.pythonhosted.org/packages/19/95/6195171e385007300f0f5574592e467c568becce2d937a0b6804f218bc49/pydantic_core-2.46.4-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:962ccbab7b642487b1d8b7df90ef677e03134cf1fd8880bf698649b22a69371f", size = 1951724, upload-time = "2026-05-06T13:37:02.697Z" },
-    { url = "https://files.pythonhosted.org/packages/8e/bc/f47d1ff9cbb1620e1b5b697eef06010035735f07820180e74178226b27b3/pydantic_core-2.46.4-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:8233f2947cf85404441fd7e0085f53b10c93e0ee78611099b5c7237e36aacbf7", size = 1975742, upload-time = "2026-05-06T13:37:09.448Z" },
-    { url = "https://files.pythonhosted.org/packages/5b/11/9b9a5b0306345664a2da6410877af6e8082481b5884b3ddd78d47c6013ce/pydantic_core-2.46.4-cp312-cp312-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:3a233125ac121aa3ffba9a2b59edfc4a985a76092dc8279586ab4b71390875e7", size = 2052418, upload-time = "2026-05-06T13:37:38.234Z" },
-    { url = "https://files.pythonhosted.org/packages/f1/b7/a65fec226f5d78fc39f4a13c4cc0c768c22b113438f60c14adc9d2865038/pydantic_core-2.46.4-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:5b712b53160b79a5850310b912a5ef8e57e56947c8ad690c227f5c9d7e561712", size = 2232274, upload-time = "2026-05-06T13:38:27.753Z" },
-    { url = "https://files.pythonhosted.org/packages/68/f0/92039db98b907ef49269a8271f67db9cb78ae2fc68062ef7e4e77adb5f61/pydantic_core-2.46.4-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:9401557acd873c3a7f3eb9383edef8ac4968f9510e340f4808d427e75667e7b4", size = 2309940, upload-time = "2026-05-06T13:38:05.353Z" },
-    { url = "https://files.pythonhosted.org/packages/5f/97/2aab507d3d00ca626e8e57c1eac6a79e4e5fbcc63eb99733ff55d1717f65/pydantic_core-2.46.4-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:926c9541b14b12b1681dca8a0b75feb510b06c6341b70a8e500c2fdcff837cce", size = 2094516, upload-time = "2026-05-06T13:39:10.577Z" },
-    { url = "https://files.pythonhosted.org/packages/22/37/a8aca44d40d737dde2bc05b3c6c07dff0de07ce6f82e9f3167aeaf4d5dea/pydantic_core-2.46.4-cp312-cp312-manylinux_2_31_riscv64.whl", hash = "sha256:56cb4851bcaf3d117eddcef4fe66afd750a50274b0da8e22be256d10e5611987", size = 2136854, upload-time = "2026-05-06T13:40:22.59Z" },
-    { url = "https://files.pythonhosted.org/packages/24/99/fcef1b79238c06a8cbec70819ac722ba76e02bc8ada9b0fd66eba40da01b/pydantic_core-2.46.4-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:c68fcd102d71ea85c5b2dfac3f4f8476eff42a9e078fd5faefff6d145063536b", size = 2180306, upload-time = "2026-05-06T13:40:10.666Z" },
-    { url = "https://files.pythonhosted.org/packages/ae/6c/fc44000918855b42779d007ae63b0532794739027b2f417321cddbc44f6a/pydantic_core-2.46.4-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:b2f69dec1725e79a012d920df1707de5caf7ed5e08f3be4435e25803efc47458", size = 2190044, upload-time = "2026-05-06T13:40:43.231Z" },
-    { url = "https://files.pythonhosted.org/packages/6b/65/d9cadc9f1920d7a127ad2edba16c1db7916e59719285cd6c94600b0080ba/pydantic_core-2.46.4-cp312-cp312-musllinux_1_1_armv7l.whl", hash = "sha256:8d0820e8192167f80d88d64038e609c31452eeca865b4e1d9950a27a4609b00b", size = 2329133, upload-time = "2026-05-06T13:39:57.365Z" },
-    { url = "https://files.pythonhosted.org/packages/d0/cf/c873d91679f3a30bcf5e7ac280ce5573483e72295307685120d0d5ad3416/pydantic_core-2.46.4-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:fbdb89b3e1c94a30cc5edfce477c6e6a5dc4d8f84665b455c27582f211a1c72c", size = 2374464, upload-time = "2026-05-06T13:38:06.976Z" },
-    { url = "https://files.pythonhosted.org/packages/47/bd/6f2fc8188f31bf10590f1e98e7b306336161fac930a8c514cd7bd828c7dc/pydantic_core-2.46.4-cp312-cp312-win32.whl", hash = "sha256:9aa768456404a8bf48a4406685ac2bec8e72b62c69313734fa3b73cf33b3a894", size = 1974823, upload-time = "2026-05-06T13:40:47.985Z" },
-    { url = "https://files.pythonhosted.org/packages/40/8c/985c1d41ea1107c2534abd9870e4ed5c8e7669b5c308297835c001e7a1c4/pydantic_core-2.46.4-cp312-cp312-win_amd64.whl", hash = "sha256:e9c26f834c65f5752f3f06cb08cb86a913ceb7274d0db6e267808a708b46bc89", size = 2072919, upload-time = "2026-05-06T13:39:21.153Z" },
-    { url = "https://files.pythonhosted.org/packages/c4/ba/f463d006e0c47373ca7ec5e1a261c59dc01ef4d62b2657af925fb0deee3a/pydantic_core-2.46.4-cp312-cp312-win_arm64.whl", hash = "sha256:4fc73cb559bdb54b1134a706a2802a4cddd27a0633f5abb7e53056268751ac6a", size = 2027604, upload-time = "2026-05-06T13:39:03.753Z" },
-    { url = "https://files.pythonhosted.org/packages/51/a2/5d30b469c5267a17b39dec53208222f76a8d351dfac4af661888c5aee77d/pydantic_core-2.46.4-cp313-cp313-macosx_10_12_x86_64.whl", hash = "sha256:5d5902252db0d3cedf8d4a1bc68f70eeb430f7e4c7104c8c476753519b423008", size = 2106306, upload-time = "2026-05-06T13:37:48.029Z" },
-    { url = "https://files.pythonhosted.org/packages/c1/81/4fa520eaffa8bd7d1525e644cd6d39e7d60b1592bc5b516693c7340b50f1/pydantic_core-2.46.4-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:c94f0688e7b8d0a67abf40e57a7eaaecd17cc9586706a31b76c031f63df052b4", size = 1951906, upload-time = "2026-05-06T13:37:17.012Z" },
-    { url = "https://files.pythonhosted.org/packages/03/d5/fd02da45b659668b05923b17ba3a0100a0a3d5541e3bd8fcc4ecb711309e/pydantic_core-2.46.4-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:f027324c56cd5406ca49c124b0db10e56c69064fec039acc571c29020cc87c76", size = 1976802, upload-time = "2026-05-06T13:37:35.113Z" },
-    { url = "https://files.pythonhosted.org/packages/21/f2/95727e1368be3d3ed485eaab7adbd7dda408f33f7a36e8b48e0144002b91/pydantic_core-2.46.4-cp313-cp313-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:e739fee756ba1010f8bcccb534252e85a35fe45ae92c295a06059ce58b74ccd3", size = 2052446, upload-time = "2026-05-06T13:37:12.313Z" },
-    { url = "https://files.pythonhosted.org/packages/9c/86/5d99feea3f77c7234b8718075b23db11532773c1a0dbd9b9490215dc2eeb/pydantic_core-2.46.4-cp313-cp313-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:9d56801be94b86a9da183e5f3766e6310752b99ff647e38b09a9500d88e46e76", size = 2232757, upload-time = "2026-05-06T13:39:01.149Z" },
-    { url = "https://files.pythonhosted.org/packages/d2/3a/508ac615935ef7588cf6d9e9b91309fdc2da751af865e02a9098de88258c/pydantic_core-2.46.4-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:2412e734dcb48da14d4e4006b82b46b74f2518b8a26ee7e58c6844a6cd6d03c4", size = 2309275, upload-time = "2026-05-06T13:37:41.406Z" },
-    { url = "https://files.pythonhosted.org/packages/07/f8/41db9de19d7987d6b04715a02b3b40aea467000275d9d758ffaa31af7d50/pydantic_core-2.46.4-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:9551187363ffc0de2a00b2e47c25aeaeb1020b69b668762966df15fc5659dd5a", size = 2094467, upload-time = "2026-05-06T13:39:18.847Z" },
-    { url = "https://files.pythonhosted.org/packages/2c/e2/f35033184cb11d0052daf4416e8e10a502ea2ac006fc4f459aee872727d1/pydantic_core-2.46.4-cp313-cp313-manylinux_2_31_riscv64.whl", hash = "sha256:0186750b482eefa11d7f435892b09c5c606193ef3375bcf94aa00ae6bfb66262", size = 2134417, upload-time = "2026-05-06T13:40:17.944Z" },
-    { url = "https://files.pythonhosted.org/packages/7e/7b/6ceeb1cc90e193862f444ebe373d8fdf613f0a82572dde03fb10734c6c71/pydantic_core-2.46.4-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:5855698a4856556d86e8e6cd8434bc3ac0314ee8e12089ae0e143f64c6256e4e", size = 2179782, upload-time = "2026-05-06T13:40:32.618Z" },
-    { url = "https://files.pythonhosted.org/packages/5a/f2/c8d7773ede6af08036423a00ae0ceffce266c3c52a096c435d68c896083f/pydantic_core-2.46.4-cp313-cp313-musllinux_1_1_aarch64.whl", hash = "sha256:cbaf13819775b7f769bf4a1f066cb6df7a28d4480081a589828ef190226881cd", size = 2188782, upload-time = "2026-05-06T13:36:51.018Z" },
-    { url = "https://files.pythonhosted.org/packages/59/31/0c864784e31f09f05cdd87606f08923b9c9e7f6e51dd27f20f62f975ce9f/pydantic_core-2.46.4-cp313-cp313-musllinux_1_1_armv7l.whl", hash = "sha256:633147d34cf4550417f12e2b1a0383973bdf5cdfde212cb09e9a581cf10820be", size = 2328334, upload-time = "2026-05-06T13:40:37.764Z" },
-    { url = "https://files.pythonhosted.org/packages/c2/eb/4f6c8a41efa30baa755590f4141abf3a8c370fab610915733e74134a7270/pydantic_core-2.46.4-cp313-cp313-musllinux_1_1_x86_64.whl", hash = "sha256:82cf5301172168103724d49a1444d3378cb20cdee30b116a1bd6031236298a5d", size = 2372986, upload-time = "2026-05-06T13:39:34.152Z" },
-    { url = "https://files.pythonhosted.org/packages/5b/24/b375a480d53113860c299764bfe9f349a3dc9108b3adc0d7f0d786492ebf/pydantic_core-2.46.4-cp313-cp313-win32.whl", hash = "sha256:9fa8ae11da9e2b3126c6426f147e0fba88d96d65921799bb30c6abd1cb2c97fb", size = 1973693, upload-time = "2026-05-06T13:37:55.072Z" },
-    { url = "https://files.pythonhosted.org/packages/7e/e8/cff247591966f2d22ec8c003cd7587e27b7ba7b81ab2fb888e3ab75dc285/pydantic_core-2.46.4-cp313-cp313-win_amd64.whl", hash = "sha256:6b3ace8194b0e5204818c92802dcdca7fc6d88aabbb799d7c795540d9cd6d292", size = 2071819, upload-time = "2026-05-06T13:38:49.139Z" },
-    { url = "https://files.pythonhosted.org/packages/c6/1a/f4aee670d5670e9e148e0c82c7db98d780be566c6e6a97ee8035528ca0b3/pydantic_core-2.46.4-cp313-cp313-win_arm64.whl", hash = "sha256:184c081504d17f1c1066e430e117142b2c77d9448a97f7b65c6ac9fd9aee238d", size = 2027411, upload-time = "2026-05-06T13:40:45.796Z" },
-    { url = "https://files.pythonhosted.org/packages/8d/74/228a26ddad29c6672b805d9fd78e8d251cd04004fa7eed0e622096cd0250/pydantic_core-2.46.4-cp314-cp314-macosx_10_12_x86_64.whl", hash = "sha256:428e04521a40150c85216fc8b85e8d39fece235a9cf5e383761238c7fa9b96fb", size = 2102079, upload-time = "2026-05-06T13:38:41.019Z" },
-    { url = "https://files.pythonhosted.org/packages/ad/1f/8970b150a4b4365623ae00fc88603491f763c627311ae8031e3111356d6e/pydantic_core-2.46.4-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:23ace664830ee0bfe014a0c7bc248b1f7f25ed7ad103852c317624a1083af462", size = 1952179, upload-time = "2026-05-06T13:36:59.812Z" },
-    { url = "https://files.pythonhosted.org/packages/95/30/5211a831ae054928054b2f79731661087a2bc5c01e825c672b3a4a8f1b3e/pydantic_core-2.46.4-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ce5c1d2a8b27468f433ca974829c44060b8097eedc39933e3c206a90ee49c4a9", size = 1978926, upload-time = "2026-05-06T13:37:39.933Z" },
-    { url = "https://files.pythonhosted.org/packages/57/e9/689668733b1eb67adeef047db3c2e8788fcf65a7fd9c9e2b46b7744fe245/pydantic_core-2.46.4-cp314-cp314-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:7283d57845ecf5a163403eb0702dfc220cc4fbdd18919cb5ccea4f95ee1cdab4", size = 2046785, upload-time = "2026-05-06T13:38:01.995Z" },
-    { url = "https://files.pythonhosted.org/packages/60/d9/6715260422ff50a2109878fd24d948a6c3446bb2664f34ee78cd972b3acd/pydantic_core-2.46.4-cp314-cp314-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:8daafc69c93ee8a0204506a3b6b30f586ef54028f52aeeeb5c4cfc5184fd5914", size = 2228733, upload-time = "2026-05-06T13:40:50.371Z" },
-    { url = "https://files.pythonhosted.org/packages/18/ae/fdb2f64316afca925640f8e70bb1a564b0ec2721c1389e25b8eb4bf9a299/pydantic_core-2.46.4-cp314-cp314-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:cd2213145bcc2ba85884d0ac63d222fece9209678f77b9b4d76f054c561adb28", size = 2307534, upload-time = "2026-05-06T13:37:21.531Z" },
-    { url = "https://files.pythonhosted.org/packages/89/1d/8eff589b45bb8190a9d12c49cfad0f176a5cbd1534908a6b5125e2886239/pydantic_core-2.46.4-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:7a5f930472650a82629163023e630d160863fce524c616f4e5186e5de9d9a49b", size = 2099732, upload-time = "2026-05-06T13:39:31.942Z" },
-    { url = "https://files.pythonhosted.org/packages/06/d5/ee5a3366637fee41dee51a1fc91562dcf12ddbc68fda34e6b253da2324bb/pydantic_core-2.46.4-cp314-cp314-manylinux_2_31_riscv64.whl", hash = "sha256:c1b3f518abeca3aa13c712fd202306e145abf59a18b094a6bafb2d2bbf59192c", size = 2129627, upload-time = "2026-05-06T13:37:25.033Z" },
-    { url = "https://files.pythonhosted.org/packages/94/33/2414be571d2c6a6c4d08be21f9292b6d3fdb08949a97b6dfe985017821db/pydantic_core-2.46.4-cp314-cp314-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:1a7dd0b3ee80d90150e3495a3a13ac34dbcbfd4f012996a6a1d8900e91b5c0fb", size = 2179141, upload-time = "2026-05-06T13:37:14.046Z" },
-    { url = "https://files.pythonhosted.org/packages/7b/79/7daa95be995be0eecc4cf75064cb33f9bbbfe3fe0158caf2f0d4a996a5c7/pydantic_core-2.46.4-cp314-cp314-musllinux_1_1_aarch64.whl", hash = "sha256:3fb702cd90b0446a3a1c5e470bfa0dd23c0233b676a9099ddcc964fa6ca13898", size = 2184325, upload-time = "2026-05-06T13:36:53.615Z" },
-    { url = "https://files.pythonhosted.org/packages/9f/cb/d0a382f5c0de8a222dc61c65348e0ce831b1f68e0a018450d31c2cace3a5/pydantic_core-2.46.4-cp314-cp314-musllinux_1_1_armv7l.whl", hash = "sha256:b8458003118a712e66286df6a707db01c52c0f52f7db8e4a38f0da1d3b94fc4e", size = 2323990, upload-time = "2026-05-06T13:40:29.971Z" },
-    { url = "https://files.pythonhosted.org/packages/05/db/d9ba624cc4a5aced1598e88c04fdbd8310c8a69b9d38b9a3d39ce3a61ed7/pydantic_core-2.46.4-cp314-cp314-musllinux_1_1_x86_64.whl", hash = "sha256:372429a130e469c9cd698925ce5fc50940b7a1336b0d82038e63d5bbc4edc519", size = 2369978, upload-time = "2026-05-06T13:37:23.027Z" },
-    { url = "https://files.pythonhosted.org/packages/f2/20/d15df15ba918c423461905802bfd2981c3af0bfa0e40d05e13edbfa48bc3/pydantic_core-2.46.4-cp314-cp314-win32.whl", hash = "sha256:85bb3611ff1802f3ee7fdd7dbff26b56f343fb432d57a4728fdd49b6ef35e2f4", size = 1966354, upload-time = "2026-05-06T13:38:03.499Z" },
-    { url = "https://files.pythonhosted.org/packages/fc/b6/6b8de4c0a7d7ab3004c439c80c5c1e0a3e8d78bbae19379b01960383d9e5/pydantic_core-2.46.4-cp314-cp314-win_amd64.whl", hash = "sha256:811ff8e9c313ab425368bcbb36e5c4ebd7108c2bbf4e4089cfbb0b01eff63fac", size = 2072238, upload-time = "2026-05-06T13:39:40.807Z" },
-    { url = "https://files.pythonhosted.org/packages/32/36/51eb763beec1f4cf59b1db243a7dcc39cbb41230f050a09b9d69faaf0a48/pydantic_core-2.46.4-cp314-cp314-win_arm64.whl", hash = "sha256:bfec22eab3c8cc2ceec0248aec886624116dc079afa027ecc8ad4a7e62010f8a", size = 2018251, upload-time = "2026-05-06T13:37:26.72Z" },
-    { url = "https://files.pythonhosted.org/packages/e8/91/855af51d625b23aa987116a19e231d2aaef9c4a415273ddc189b79a45fee/pydantic_core-2.46.4-cp314-cp314t-macosx_10_12_x86_64.whl", hash = "sha256:af8244b2bef6aaad6d92cda81372de7f8c8d36c9f0c3ea36e827c60e7d9467a0", size = 2099593, upload-time = "2026-05-06T13:39:47.682Z" },
-    { url = "https://files.pythonhosted.org/packages/fb/1b/8784a54c65edb5f49f0a14d6977cf1b209bba85a4c77445b255c2de58ab3/pydantic_core-2.46.4-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:5a4330cdbc57162e4b3aa303f588ba752257694c9c9be3e7ebb11b4aca659b5d", size = 1935226, upload-time = "2026-05-06T13:40:40.428Z" },
-    { url = "https://files.pythonhosted.org/packages/e8/e7/1955d28d1afc56dd4b3ad7cc0cf39df1b9852964cf16e5d13912756d6d6b/pydantic_core-2.46.4-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:29c61fc04a3d840155ff08e475a04809278972fe6aef51e2720554e96367e34b", size = 1974605, upload-time = "2026-05-06T13:37:32.029Z" },
-    { url = "https://files.pythonhosted.org/packages/93/e2/3fedbf0ba7a22850e6e9fd78117f1c0f10f950182344d8a6c535d468fdd8/pydantic_core-2.46.4-cp314-cp314t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:c50f2528cf200c5eed56faf3f4e22fcd5f38c157a8b78576e6ba3168ec35f000", size = 2030777, upload-time = "2026-05-06T13:38:55.239Z" },
-    { url = "https://files.pythonhosted.org/packages/f8/61/46be275fcaaba0b4f5b9669dd852267ce1ff616592dccf7a7845588df091/pydantic_core-2.46.4-cp314-cp314t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:0cbe8b01f948de4286c74cdd6c667aceb38f5c1e26f0693b3983d9d74887c65e", size = 2236641, upload-time = "2026-05-06T13:37:08.096Z" },
-    { url = "https://files.pythonhosted.org/packages/60/db/12e93e46a8bac9988be3c016860f83293daea8c716c029c9ace279036f2f/pydantic_core-2.46.4-cp314-cp314t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:617d7e2ca7dcb8c5cf6bcb8c59b8832c94b36196bbf1cbd1bfb56ed341905edd", size = 2286404, upload-time = "2026-05-06T13:40:20.221Z" },
-    { url = "https://files.pythonhosted.org/packages/e2/4a/4d8b19008f38d31c53b8219cfedc2e3d5de5fe99d90076b7e767de29274f/pydantic_core-2.46.4-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:7027560ee92211647d0d34e3f7cd6f50da56399d26a9c8ad0da286d3869a53f3", size = 2109219, upload-time = "2026-05-06T13:38:12.153Z" },
-    { url = "https://files.pythonhosted.org/packages/88/70/3cbc40978fefb7bb09c6708d40d4ad1a5d70fd7213c3d17f971de868ec1f/pydantic_core-2.46.4-cp314-cp314t-manylinux_2_31_riscv64.whl", hash = "sha256:f99626688942fb746e545232e7726926f3be91b5975f8b55327665fafda991c7", size = 2110594, upload-time = "2026-05-06T13:40:02.971Z" },
-    { url = "https://files.pythonhosted.org/packages/9d/20/b8d36736216e29491125531685b2f9e61aa5b4b2599893f8268551da3338/pydantic_core-2.46.4-cp314-cp314t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:fc3e9034a63de20e15e8ade85358bc6efc614008cab72898b4b4952bea0509ff", size = 2159542, upload-time = "2026-05-06T13:39:27.506Z" },
-    { url = "https://files.pythonhosted.org/packages/1d/a2/367df868eb584dacf6bf82a389272406d7178e301c4ac82545ab98bc2dd9/pydantic_core-2.46.4-cp314-cp314t-musllinux_1_1_aarch64.whl", hash = "sha256:97e7cf2be5c77b7d1a9713a05605d49460d02c6078d38d8bef3cbe323c548424", size = 2168146, upload-time = "2026-05-06T13:38:31.93Z" },
-    { url = "https://files.pythonhosted.org/packages/c1/b8/4460f77f7e201893f649a29ab355dddd3beee8a97bcb1a320db414f9a06e/pydantic_core-2.46.4-cp314-cp314t-musllinux_1_1_armv7l.whl", hash = "sha256:3bf92c5d0e00fefaab325a4d27828fe6b6e2a21848686b5b60d2d9eeb09d76c6", size = 2306309, upload-time = "2026-05-06T13:37:44.717Z" },
-    { url = "https://files.pythonhosted.org/packages/64/c4/be2639293acd87dc8ddbcec41a73cee9b2ebf996fe6d892a1a74e88ad3f7/pydantic_core-2.46.4-cp314-cp314t-musllinux_1_1_x86_64.whl", hash = "sha256:3ecbc122d18468d06ca279dc26a8c2e2d5acb10943bb35e36ae92096dc3b5565", size = 2369736, upload-time = "2026-05-06T13:37:05.645Z" },
-    { url = "https://files.pythonhosted.org/packages/30/a6/9f9f380dbb301f67023bf8f707aaa75daadf84f7152d95c410fd7e81d994/pydantic_core-2.46.4-cp314-cp314t-win32.whl", hash = "sha256:e846ae7835bf0703ae43f534ab79a867146dadd59dc9ca5c8b53d5c8f7c9ef02", size = 1955575, upload-time = "2026-05-06T13:38:51.116Z" },
-    { url = "https://files.pythonhosted.org/packages/40/1f/f1eb9eb350e795d1af8586289746f5c5677d16043040d63710e22abc43c9/pydantic_core-2.46.4-cp314-cp314t-win_amd64.whl", hash = "sha256:2108ba5c1c1eca18030634489dc544844144ee36357f2f9f780b93e7ddbb44b5", size = 2051624, upload-time = "2026-05-06T13:38:21.672Z" },
-    { url = "https://files.pythonhosted.org/packages/f6/d2/42dd53d0a85c27606f316d3aa5d2869c4e8470a5ed6dec30e4a1abe19192/pydantic_core-2.46.4-cp314-cp314t-win_arm64.whl", hash = "sha256:4fcbe087dbc2068af7eda3aa87634eba216dbda64d1ae73c8684b621d33f6596", size = 2017325, upload-time = "2026-05-06T13:40:52.723Z" },
-    { url = "https://files.pythonhosted.org/packages/9d/1d/8987ad40f65ae1432753072f214fb5c74fe47ffbd0698bb9cbbb585664f8/pydantic_core-2.46.4-graalpy312-graalpy250_312_native-macosx_10_12_x86_64.whl", hash = "sha256:1d8ba486450b14f3b1d63bc521d410ec7565e52f887b9fb671791886436a42f7", size = 2095527, upload-time = "2026-05-06T13:39:52.283Z" },
-    { url = "https://files.pythonhosted.org/packages/64/d3/84c282a7eee1d3ac4c0377546ef5a1ea436ce26840d9ac3b7ed54a377507/pydantic_core-2.46.4-graalpy312-graalpy250_312_native-macosx_11_0_arm64.whl", hash = "sha256:3009f12e4e90b7f88b4f9adb1b0c4a3d58fe7820f3238c190047209d148026df", size = 1936024, upload-time = "2026-05-06T13:40:15.671Z" },
-    { url = "https://files.pythonhosted.org/packages/d7/ca/eac61596cdeb4d7e174d3dc0bd8a6238f14f75f97a24e7b7db4c7e7340a0/pydantic_core-2.46.4-graalpy312-graalpy250_312_native-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ad785e92e6dc634c21555edc8bd6b64957ab844541bcb96a1366c202951ae526", size = 1990696, upload-time = "2026-05-06T13:38:34.717Z" },
-    { url = "https://files.pythonhosted.org/packages/fa/c3/7c8b240552251faf6b3a957db200fcfbbcec36763c050428b601e0c9b83b/pydantic_core-2.46.4-graalpy312-graalpy250_312_native-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:00c603d540afdd6b80eb39f078f33ebd46211f02f33e34a32d9f053bba711de0", size = 2147590, upload-time = "2026-05-06T13:39:29.883Z" },
-]
-
-[[package]]
-name = "pydantic-settings"
-version = "2.14.1"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "pydantic" },
-    { name = "python-dotenv" },
-    { name = "typing-inspection" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/07/60/1d1e59c9c90d54591469ada7d268251f71c24bdb765f1a8a832cee8c6653/pydantic_settings-2.14.1.tar.gz", hash = "sha256:e874d3bec7e787b0c9958277956ed9b4dd5de6a80e162188fdaff7c5e26fd5fa", size = 235551, upload-time = "2026-05-08T13:40:06.542Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/ae/8d/f1af3832f5e6eb13ba94ee809e72b8ecb5eef226d27ee0bef7d963d943c7/pydantic_settings-2.14.1-py3-none-any.whl", hash = "sha256:6e3c7edfd8277687cdc598f56e5cff0e9bfff0910a3749deaa8d4401c3a2b9de", size = 60964, upload-time = "2026-05-08T13:40:04.958Z" },
-]
-
-[[package]]
-name = "pygments"
-version = "2.20.0"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/c3/b2/bc9c9196916376152d655522fdcebac55e66de6603a76a02bca1b6414f6c/pygments-2.20.0.tar.gz", hash = "sha256:6757cd03768053ff99f3039c1a36d6c0aa0b263438fcab17520b30a303a82b5f", size = 4955991, upload-time = "2026-03-29T13:29:33.898Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/f4/7e/a72dd26f3b0f4f2bf1dd8923c85f7ceb43172af56d63c7383eb62b332364/pygments-2.20.0-py3-none-any.whl", hash = "sha256:81a9e26dd42fd28a23a2d169d86d7ac03b46e2f8b59ed4698fb4785f946d0176", size = 1231151, upload-time = "2026-03-29T13:29:30.038Z" },
-]
-
-[[package]]
-name = "pyjwt"
-version = "2.12.1"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/c2/27/a3b6e5bf6ff856d2509292e95c8f57f0df7017cf5394921fc4e4ef40308a/pyjwt-2.12.1.tar.gz", hash = "sha256:c74a7a2adf861c04d002db713dd85f84beb242228e671280bf709d765b03672b", size = 102564, upload-time = "2026-03-13T19:27:37.25Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/e5/7a/8dd906bd22e79e47397a61742927f6747fe93242ef86645ee9092e610244/pyjwt-2.12.1-py3-none-any.whl", hash = "sha256:28ca37c070cad8ba8cd9790cd940535d40274d22f80ab87f3ac6a713e6e8454c", size = 29726, upload-time = "2026-03-13T19:27:35.677Z" },
-]
-
-[package.optional-dependencies]
-crypto = [
-    { name = "cryptography" },
-]
-
-[[package]]
-name = "python-dotenv"
-version = "1.2.2"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/82/ed/0301aeeac3e5353ef3d94b6ec08bbcabd04a72018415dcb29e588514bba8/python_dotenv-1.2.2.tar.gz", hash = "sha256:2c371a91fbd7ba082c2c1dc1f8bf89ca22564a087c2c287cd9b662adde799cf3", size = 50135, upload-time = "2026-03-01T16:00:26.196Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/0b/d7/1959b9648791274998a9c3526f6d0ec8fd2233e4d4acce81bbae76b44b2a/python_dotenv-1.2.2-py3-none-any.whl", hash = "sha256:1d8214789a24de455a8b8bd8ae6fe3c6b69a5e3d64aa8a8e5d68e694bbcb285a", size = 22101, upload-time = "2026-03-01T16:00:25.09Z" },
-]
-
-[[package]]
-name = "python-multipart"
-version = "0.0.28"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/82/54/a85eb421fbdd5007bc5af39d0f4ed9fa609e0fedbfdc2adcf0b34526870e/python_multipart-0.0.28.tar.gz", hash = "sha256:8550da197eac0f7ab748961fc9509b999fa2662ea25cef857f05249f6893c0f8", size = 45314, upload-time = "2026-05-10T11:05:16.596Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/f3/a2/43bbc5860b5034e2af4ef99a0e04d726ff329c43e192ef3abaa8d7ecfce5/python_multipart-0.0.28-py3-none-any.whl", hash = "sha256:10faac07eb966c3f48dc415f9dee46c04cb10d58d30a35677db8027c825ed9b6", size = 29438, upload-time = "2026-05-10T11:05:15.052Z" },
-]
-
-[[package]]
-name = "pywin32"
-version = "311"
-source = { registry = "https://pypi.org/simple" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/e7/ab/01ea1943d4eba0f850c3c61e78e8dd59757ff815ff3ccd0a84de5f541f42/pywin32-311-cp312-cp312-win32.whl", hash = "sha256:750ec6e621af2b948540032557b10a2d43b0cee2ae9758c54154d711cc852d31", size = 8706543, upload-time = "2025-07-14T20:13:20.765Z" },
-    { url = "https://files.pythonhosted.org/packages/d1/a8/a0e8d07d4d051ec7502cd58b291ec98dcc0c3fff027caad0470b72cfcc2f/pywin32-311-cp312-cp312-win_amd64.whl", hash = "sha256:b8c095edad5c211ff31c05223658e71bf7116daa0ecf3ad85f3201ea3190d067", size = 9495040, upload-time = "2025-07-14T20:13:22.543Z" },
-    { url = "https://files.pythonhosted.org/packages/ba/3a/2ae996277b4b50f17d61f0603efd8253cb2d79cc7ae159468007b586396d/pywin32-311-cp312-cp312-win_arm64.whl", hash = "sha256:e286f46a9a39c4a18b319c28f59b61de793654af2f395c102b4f819e584b5852", size = 8710102, upload-time = "2025-07-14T20:13:24.682Z" },
-    { url = "https://files.pythonhosted.org/packages/a5/be/3fd5de0979fcb3994bfee0d65ed8ca9506a8a1260651b86174f6a86f52b3/pywin32-311-cp313-cp313-win32.whl", hash = "sha256:f95ba5a847cba10dd8c4d8fefa9f2a6cf283b8b88ed6178fa8a6c1ab16054d0d", size = 8705700, upload-time = "2025-07-14T20:13:26.471Z" },
-    { url = "https://files.pythonhosted.org/packages/e3/28/e0a1909523c6890208295a29e05c2adb2126364e289826c0a8bc7297bd5c/pywin32-311-cp313-cp313-win_amd64.whl", hash = "sha256:718a38f7e5b058e76aee1c56ddd06908116d35147e133427e59a3983f703a20d", size = 9494700, upload-time = "2025-07-14T20:13:28.243Z" },
-    { url = "https://files.pythonhosted.org/packages/04/bf/90339ac0f55726dce7d794e6d79a18a91265bdf3aa70b6b9ca52f35e022a/pywin32-311-cp313-cp313-win_arm64.whl", hash = "sha256:7b4075d959648406202d92a2310cb990fea19b535c7f4a78d3f5e10b926eeb8a", size = 8709318, upload-time = "2025-07-14T20:13:30.348Z" },
-    { url = "https://files.pythonhosted.org/packages/c9/31/097f2e132c4f16d99a22bfb777e0fd88bd8e1c634304e102f313af69ace5/pywin32-311-cp314-cp314-win32.whl", hash = "sha256:b7a2c10b93f8986666d0c803ee19b5990885872a7de910fc460f9b0c2fbf92ee", size = 8840714, upload-time = "2025-07-14T20:13:32.449Z" },
-    { url = "https://files.pythonhosted.org/packages/90/4b/07c77d8ba0e01349358082713400435347df8426208171ce297da32c313d/pywin32-311-cp314-cp314-win_amd64.whl", hash = "sha256:3aca44c046bd2ed8c90de9cb8427f581c479e594e99b5c0bb19b29c10fd6cb87", size = 9656800, upload-time = "2025-07-14T20:13:34.312Z" },
-    { url = "https://files.pythonhosted.org/packages/c0/d2/21af5c535501a7233e734b8af901574572da66fcc254cb35d0609c9080dd/pywin32-311-cp314-cp314-win_arm64.whl", hash = "sha256:a508e2d9025764a8270f93111a970e1d0fbfc33f4153b388bb649b7eec4f9b42", size = 8932540, upload-time = "2025-07-14T20:13:36.379Z" },
-]
-
-[[package]]
-name = "referencing"
-version = "0.37.0"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "attrs" },
-    { name = "rpds-py" },
-    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/22/f5/df4e9027acead3ecc63e50fe1e36aca1523e1719559c499951bb4b53188f/referencing-0.37.0.tar.gz", hash = "sha256:44aefc3142c5b842538163acb373e24cce6632bd54bdb01b21ad5863489f50d8", size = 78036, upload-time = "2025-10-13T15:30:48.871Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/2c/58/ca301544e1fa93ed4f80d724bf5b194f6e4b945841c5bfd555878eea9fcb/referencing-0.37.0-py3-none-any.whl", hash = "sha256:381329a9f99628c9069361716891d34ad94af76e461dcb0335825aecc7692231", size = 26766, upload-time = "2025-10-13T15:30:47.625Z" },
-]
-
-[[package]]
-name = "regex"
-version = "2026.5.9"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/dc/0e/49aee608ad09480e7fd276898c99ec6192985fa331abe4eb3a986094490b/regex-2026.5.9.tar.gz", hash = "sha256:a8234aa23ec39894bfe4a3f1b85616a7032481964a13ac6fc9f10de4f6fca270", size = 416074, upload-time = "2026-05-09T23:15:19.37Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/50/9b/6550044bc44e17c84d312c031c2ec42fbdb6a4ec4e29093be3a172d08772/regex-2026.5.9-cp312-cp312-macosx_10_13_universal2.whl", hash = "sha256:57eeeb05db7979413dec5438f2db21d7ecbba787cde7a711df1a6f6df672aa06", size = 490451, upload-time = "2026-05-09T23:12:34.72Z" },
-    { url = "https://files.pythonhosted.org/packages/1e/95/fc7ba4303b5a0f92446a12ee6778ef2c6c799233f5060042a31bf390cfe9/regex-2026.5.9-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:398c521292f4c7fb807001dcd54694d3a1fcafc179a36ad9cc56f98df85930b6", size = 292112, upload-time = "2026-05-09T23:12:36.285Z" },
-    { url = "https://files.pythonhosted.org/packages/54/4b/ee27938d1b2c443e89a9a10e00d2d19aa5ee300cd3d61140644e93bb083e/regex-2026.5.9-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:f7a7c26137296beba7784de6eba69c6a93a63ccebc385e4962fe67e267a91225", size = 289599, upload-time = "2026-05-09T23:12:38.089Z" },
-    { url = "https://files.pythonhosted.org/packages/d8/dd/ba103dc19614e25f3880800ca67ce093d6e21b325d72b8383c7bf906e9fa/regex-2026.5.9-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:6441cc660d76107934a09c22167200839a0e89604a6297f78a974e66e931d2c0", size = 796732, upload-time = "2026-05-09T23:12:40.062Z" },
-    { url = "https://files.pythonhosted.org/packages/cf/e7/f035b4fd858b050b0080bf302968dc0f59ba34e391872d54936758e6844e/regex-2026.5.9-cp312-cp312-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:91328f1c23d47595ca3ef0a7557fa129c5a23404b775c770697d2f35b33e0107", size = 865440, upload-time = "2026-05-09T23:12:42.059Z" },
-    { url = "https://files.pythonhosted.org/packages/0a/51/8cd301ecc899aea28124357f729f4272f44de7806fc7ca02490bfbe253e8/regex-2026.5.9-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:93a7860539414dddaefba2b40f8771765ae17949d4c7182b876ce429e11a8309", size = 912329, upload-time = "2026-05-09T23:12:44.373Z" },
-    { url = "https://files.pythonhosted.org/packages/cc/1e/3fbe2fa1e8cebd62f3bb7d3321cff1640aca2e240b51d9bd624aad949260/regex-2026.5.9-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:dd2810d22146b6d838acc5ec15602cb6b47920aa4e33015df3868eedfd20bab8", size = 801239, upload-time = "2026-05-09T23:12:46.268Z" },
-    { url = "https://files.pythonhosted.org/packages/17/2f/6f6008682bf2cf98040a0d3153a8e557b6ab728d7713d045cee4ce544ab8/regex-2026.5.9-cp312-cp312-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:daff2bdbaf1d23e52fdff7c0b7bc2048b68f978df6a4d107ac981f94caef2e66", size = 777054, upload-time = "2026-05-09T23:12:48.051Z" },
-    { url = "https://files.pythonhosted.org/packages/19/2b/eee0d20a6842ba04df4b8847a920b57ef56853f14ef85405473e586b605a/regex-2026.5.9-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:4eeb011098fcb77af513dcef521a3dbecbf8849b1e38940759d293b7a93f5026", size = 785098, upload-time = "2026-05-09T23:12:49.851Z" },
-    { url = "https://files.pythonhosted.org/packages/4a/98/6fc1e6410feefb92159edaed5041992bfe390e8d26c721865434acbca558/regex-2026.5.9-cp312-cp312-musllinux_1_2_ppc64le.whl", hash = "sha256:ea9c8ecfa1b73c73b626534d6626e5340d429630943672b8480724f44e84b962", size = 860095, upload-time = "2026-05-09T23:12:51.666Z" },
-    { url = "https://files.pythonhosted.org/packages/18/a3/bd855e0f2cb1a978ecf6fa6bb69632dd9c3f6ea3b81cde62fde14c9daec7/regex-2026.5.9-cp312-cp312-musllinux_1_2_riscv64.whl", hash = "sha256:cd2846168eb9ee3c513902bc8225409cb1caab31d04728b145171fa1625d9621", size = 765762, upload-time = "2026-05-09T23:12:53.413Z" },
-    { url = "https://files.pythonhosted.org/packages/dc/66/0ae8c092e60b14c79d24f8e0b7f0aea5bfbffdcab00b5483d13404d3c3a5/regex-2026.5.9-cp312-cp312-musllinux_1_2_s390x.whl", hash = "sha256:39617fb0cde9c0e6306dc70e3bfc096f3da793219879f7ae7aa341a69fbdcf6d", size = 852100, upload-time = "2026-05-09T23:12:55.256Z" },
-    { url = "https://files.pythonhosted.org/packages/21/de/8dfde60fc1b21c946a893ba273403b72617edb261370cb1087099a83f088/regex-2026.5.9-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:fd03c4f0e33280d15cae17159b899245d6b7c53d21def19b263b39655061f5ce", size = 789479, upload-time = "2026-05-09T23:12:57.573Z" },
-    { url = "https://files.pythonhosted.org/packages/c3/1c/bdcc98f9a4af4fdd166c74941174619ccff4726d3ce32faa8e9a2ecd38dd/regex-2026.5.9-cp312-cp312-win32.whl", hash = "sha256:164eba9b755ea6f244b0d881196fbc1fac09714e9782c9e2732b813142033c8e", size = 266699, upload-time = "2026-05-09T23:12:59.14Z" },
-    { url = "https://files.pythonhosted.org/packages/78/87/240d36864f9e48ace85f72e79ced97ceb7f27ce87739a947dcb834b4e6bc/regex-2026.5.9-cp312-cp312-win_amd64.whl", hash = "sha256:86f40a5d6444db30a125c9c9177e6b25dad981cbc37451fd838f145e6edac92e", size = 277783, upload-time = "2026-05-09T23:13:00.789Z" },
-    { url = "https://files.pythonhosted.org/packages/4f/b5/7b30f312b0669dff5beebe5b0989dc2d1a312b1a44fab852199c387a5b96/regex-2026.5.9-cp312-cp312-win_arm64.whl", hash = "sha256:96f5f58b54a063d7ea9dca08e1cf57bfe10499c4d579ee672da284f57f5f0070", size = 270513, upload-time = "2026-05-09T23:13:02.426Z" },
-    { url = "https://files.pythonhosted.org/packages/aa/da/797e91ecec6f84135da778ddce78c20e0af5d2a15c26f87a81bc3eadb6db/regex-2026.5.9-cp313-cp313-macosx_10_13_universal2.whl", hash = "sha256:d626b84406444b165fc0ba981604edea39f0588ff1f92baa23fe50799ea9afdb", size = 490303, upload-time = "2026-05-09T23:13:04.382Z" },
-    { url = "https://files.pythonhosted.org/packages/44/da/bf30abaaa737b58f4a4b8c4a03659e02fd92092c822e0197ed9e0daab917/regex-2026.5.9-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:d7bdc0ab8f3dd7e1b4f9ab88634e13374669db86bb3c72e8292f07ae313f539f", size = 292019, upload-time = "2026-05-09T23:13:06.022Z" },
-    { url = "https://files.pythonhosted.org/packages/2d/e7/d0eaf5713828417b9e5648cf81fa9bacd4961f6ab98c380c2034f8716e35/regex-2026.5.9-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:a8820737949116ffff55fe18f9fc644530063ba6ebfcb8314239416e78f1347c", size = 289468, upload-time = "2026-05-09T23:13:08.214Z" },
-    { url = "https://files.pythonhosted.org/packages/d3/9b/b3fdd62b003baa1a9b593cd8c8699c9651c2e80cc21a5c715707983c42d7/regex-2026.5.9-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:aa0fbdbac82cb3e4450d0ccde7d7a35607f4cb2dd9fba4b8b69bfaf8c9fa6aed", size = 796749, upload-time = "2026-05-09T23:13:10.573Z" },
-    { url = "https://files.pythonhosted.org/packages/d4/30/66ab84588765f5b4b271a9ca09ef7ce2b87caa95176ec3d2ad65d7bc4902/regex-2026.5.9-cp313-cp313-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:57e8915c7986aa33d25e4d3629cef711cd2863f2961b10409f0c04cb8b7d9020", size = 865445, upload-time = "2026-05-09T23:13:12.523Z" },
-    { url = "https://files.pythonhosted.org/packages/1a/89/f05169e8588aac365f35ffc7f3bc3184f095ef4cfded7cfaa3c7fd5dbd89/regex-2026.5.9-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:508f56a89ba9cb26e4168cbc37dbd60a28d82430a9e18ad1d25fe0883c314ca2", size = 912322, upload-time = "2026-05-09T23:13:14.281Z" },
-    { url = "https://files.pythonhosted.org/packages/30/e1/c93444052cf41581f3c884ab3fb5823daf0992f11cd4388d4275ca610558/regex-2026.5.9-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:b6d189041f15691cfa2b6c4290448ec221244d225b3f5fe9e7771b34ffcdf6e2", size = 801269, upload-time = "2026-05-09T23:13:16.569Z" },
-    { url = "https://files.pythonhosted.org/packages/50/fe/0cf96b882f540e62e8b9956599798203d599c44cf4c77917ca27400ff69b/regex-2026.5.9-cp313-cp313-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:e82db382b44d0111b22601c509c89f64434816c9e0eef9d1989cda8cc6ff1c04", size = 777085, upload-time = "2026-05-09T23:13:18.675Z" },
-    { url = "https://files.pythonhosted.org/packages/23/5c/d78d4924e7fc875557b9e9b768423925fdfaac5549d06da7810019a9bd26/regex-2026.5.9-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:2acfb48634f64996b57f90f39afa692ff362162722581921fe92239a59960f3c", size = 785153, upload-time = "2026-05-09T23:13:20.525Z" },
-    { url = "https://files.pythonhosted.org/packages/bf/e0/5214774090e7b4524dcea3e3c4aa74141d43043f8beb49c1599db1c8b53a/regex-2026.5.9-cp313-cp313-musllinux_1_2_ppc64le.whl", hash = "sha256:d29eebfc9525db68cad3c97eedd7f754fa265aa5cd0cf4f863b2421e1b48fc9f", size = 860164, upload-time = "2026-05-09T23:13:22.263Z" },
-    { url = "https://files.pythonhosted.org/packages/6e/e1/4a57a83350319b1271f0d7a249b8672513ed928b237a741631270de6caea/regex-2026.5.9-cp313-cp313-musllinux_1_2_riscv64.whl", hash = "sha256:debb893095e944091c16e641a6e33c1b0f4cb61ab945ec5afbf53ce7068834d8", size = 765731, upload-time = "2026-05-09T23:13:24.277Z" },
-    { url = "https://files.pythonhosted.org/packages/12/f4/499e74a20c156fc75836ee04a72a38d1a063978f600937f9760467beb1b0/regex-2026.5.9-cp313-cp313-musllinux_1_2_s390x.whl", hash = "sha256:d659eee77986549c9ea45b861c7567e44d6287c3dc9a4565478853f7b9fe2ff6", size = 852062, upload-time = "2026-05-09T23:13:26.125Z" },
-    { url = "https://files.pythonhosted.org/packages/5b/92/7eebc0d0a01e78629695f342ba17e0deaff8fb45e79cc0d7b98287da6e3e/regex-2026.5.9-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:2efa205e6d98b24d1f3ab395c11aa15cdf10935bca283d0285e0499c284fba21", size = 789577, upload-time = "2026-05-09T23:13:27.814Z" },
-    { url = "https://files.pythonhosted.org/packages/05/a4/018e71f7d2ad48c1ebe6d3ae0026f9b7cb4802fd15c7cc02fdf724355102/regex-2026.5.9-cp313-cp313-win32.whl", hash = "sha256:f3844f134e834076677dd369976e9f5068679fcb8e50102fdf6b7ac96a3ec127", size = 266691, upload-time = "2026-05-09T23:13:29.549Z" },
-    { url = "https://files.pythonhosted.org/packages/e6/1d/861a93719fb9ee7dbfc3761b3797b7a3e112a5d42c6129459d2d741be9b5/regex-2026.5.9-cp313-cp313-win_amd64.whl", hash = "sha256:3527bb4942d2c14552155406cdedd906567456821848aed1cb4933a391bf5eca", size = 277747, upload-time = "2026-05-09T23:13:31.859Z" },
-    { url = "https://files.pythonhosted.org/packages/d9/c6/0a2436ae4da1ba76e51cb98943c6838a9a721faa40ebe2dce07694ae34e3/regex-2026.5.9-cp313-cp313-win_arm64.whl", hash = "sha256:56a33f191f17d8c417f99945ebdc1e691d3af9605d86ec68c7e54a57e3e17af6", size = 270500, upload-time = "2026-05-09T23:13:33.525Z" },
-    { url = "https://files.pythonhosted.org/packages/e8/e9/d21346f7b60ed58789371358ed66b09d00f832e1bd7c06e55d9da5679882/regex-2026.5.9-cp313-cp313t-macosx_10_13_universal2.whl", hash = "sha256:01f28d868834624c934b8d2e0aa1c8341337e37831f4a012f18a5afcba4cbaf3", size = 494172, upload-time = "2026-05-09T23:13:35.935Z" },
-    { url = "https://files.pythonhosted.org/packages/c4/43/fd1177a2032037c681baecdb3422ee4e1424aec4e4f470ef47793d325274/regex-2026.5.9-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:48036f6374aaa79eb3b754ec29c61d1c6b1606749d705a13f8854fa2539671f6", size = 293952, upload-time = "2026-05-09T23:13:38.307Z" },
-    { url = "https://files.pythonhosted.org/packages/f2/7d/9fbf919768368d3f8a4f6c692cf2aa61e482b2b81ec6a298ace4cbf02480/regex-2026.5.9-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:b96350aa424e79d4fd6b567b344dcbe2b2d6bfc48dfe7717587e1fa6d43da6ff", size = 292314, upload-time = "2026-05-09T23:13:40.353Z" },
-    { url = "https://files.pythonhosted.org/packages/e2/6c/e41bfeecb589716843e7c4df09ba46ff2a42961457afece19059d85caeef/regex-2026.5.9-cp313-cp313t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:8f3af7a4903c5c04a11a196a5aa75cdd7dd3f8508132f9fb3259d9f5908e3b88", size = 811681, upload-time = "2026-05-09T23:13:42.543Z" },
-    { url = "https://files.pythonhosted.org/packages/87/83/a5c1c525fba0aa656e88ad0face0b1829788ef4c2fb6b26df58aa1151b84/regex-2026.5.9-cp313-cp313t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:7e87577720152d2caae19fe2baaf1f8d5ca12091e9e229f03915c37d1e4b9178", size = 871135, upload-time = "2026-05-09T23:13:44.326Z" },
-    { url = "https://files.pythonhosted.org/packages/18/d4/80882e799e440dd878b0979cbebf8fa4d54624a332c83037c7a701649e3f/regex-2026.5.9-cp313-cp313t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:c8b9b9d294cfea3cd19c718ade7cc93492b2c4991abd9a68d0b3477ae6d8e100", size = 917265, upload-time = "2026-05-09T23:13:47.295Z" },
-    { url = "https://files.pythonhosted.org/packages/ae/ff/8db60211e2286e396aad7dc7725356c502bff0901ea05bd6cdc2e1a042b9/regex-2026.5.9-cp313-cp313t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:728d8bfd28a8845c8b6bc5dc7ce010453d206396786c0765c2740cb65f37791e", size = 816311, upload-time = "2026-05-09T23:13:49.885Z" },
-    { url = "https://files.pythonhosted.org/packages/4c/47/742ef579c61730f8d268e5cf1f9ce0e37e2ea041ad0f5644724f2378e463/regex-2026.5.9-cp313-cp313t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:7e30b874d341fac767d7df5a0870540541c2c054b80cfaac116e8d367a8a7ff2", size = 785498, upload-time = "2026-05-09T23:13:52.25Z" },
-    { url = "https://files.pythonhosted.org/packages/7f/ab/cb0999802dcb0fb95b1ab005e8d4163d8afdd67efc2cb6b6630ac13f8cb1/regex-2026.5.9-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:fd190e88a895a8901325fad284a3f74ea52b1da8525b76cc811fa9b1edf0ce2b", size = 801348, upload-time = "2026-05-09T23:13:54.127Z" },
-    { url = "https://files.pythonhosted.org/packages/7d/62/8ca59a24c55bc34d166eefaf3717bd77772f329fdbf984d86581e0a3571c/regex-2026.5.9-cp313-cp313t-musllinux_1_2_ppc64le.whl", hash = "sha256:8e76e8161ad00694cfce6767d5dea860c6391ac5b83e5c3a39661e696f11fc7e", size = 866493, upload-time = "2026-05-09T23:13:56.067Z" },
-    { url = "https://files.pythonhosted.org/packages/8d/3d/30f2ae62cef3278bb5bb821f467277a55fb73f01032cf85997e15e8289a8/regex-2026.5.9-cp313-cp313t-musllinux_1_2_riscv64.whl", hash = "sha256:ddda5340e6c01a293027dd46232fa79eaff1b48058ce7a98f572b6445b088041", size = 772811, upload-time = "2026-05-09T23:13:57.867Z" },
-    { url = "https://files.pythonhosted.org/packages/d8/ae/7d2089bcd78ad0c0161bc684339df50032acb438a7bd3305e7ddb1193cec/regex-2026.5.9-cp313-cp313t-musllinux_1_2_s390x.whl", hash = "sha256:205109e96b3cf5adf8f4cd62bedde9487feb282b9497a3535451e5a24cd706a0", size = 856584, upload-time = "2026-05-09T23:13:59.679Z" },
-    { url = "https://files.pythonhosted.org/packages/a9/29/92ff47f75990131ea4f24ba17819e5a9d141e10819807e09addd73409af6/regex-2026.5.9-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:dfbe4579b9f08036aa7d101d1835437a20783574ac66327e6b29b4018a138081", size = 803453, upload-time = "2026-05-09T23:14:01.978Z" },
-    { url = "https://files.pythonhosted.org/packages/04/99/eff29f1037dcab36702c9ee5d6858cf1ce2336ea8ea2987f64245b99ea5e/regex-2026.5.9-cp313-cp313t-win32.whl", hash = "sha256:ed2c9e8068b614c574d8d30e543d617cf5379b0535d46f97ef00e904745a08b5", size = 269951, upload-time = "2026-05-09T23:14:03.661Z" },
-    { url = "https://files.pythonhosted.org/packages/0e/9d/8870b8981d27b22cda77bb26a5ac7ebfa9c7d9e0dea195a834a82380e748/regex-2026.5.9-cp313-cp313t-win_amd64.whl", hash = "sha256:b46b0f094dc1d3b90356c85a0bd2c9bafc4a6a190b9d6f8ddd5a033b6e088ed4", size = 281240, upload-time = "2026-05-09T23:14:05.56Z" },
-    { url = "https://files.pythonhosted.org/packages/72/b1/3379415e8f135c13ac551353397cc4fe97b4978f3cac73c5fcbcded548b8/regex-2026.5.9-cp313-cp313t-win_arm64.whl", hash = "sha256:872acc074bd29ffc9913ecdfedf6ea77502312ca44a4aa0d3779089c6069d8de", size = 272383, upload-time = "2026-05-09T23:14:07.843Z" },
-    { url = "https://files.pythonhosted.org/packages/13/3e/9c3cd292d8808b3645a2ce517e200179b6d0e903f176300bd8b542e14de5/regex-2026.5.9-cp314-cp314-macosx_10_13_universal2.whl", hash = "sha256:1bd7587a2948b4085195d5a3374eaf4a425dc3e55784c038175355ecf3bbbf8a", size = 490376, upload-time = "2026-05-09T23:14:09.64Z" },
-    { url = "https://files.pythonhosted.org/packages/60/70/d43ee8a2ca0a8b68d167f21658b85520ac0574617c7f320367c5047f7556/regex-2026.5.9-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:dea2e88e1cce4522496cce630e11e67b98b7076620bc4336c3f674bc21a375f4", size = 291964, upload-time = "2026-05-09T23:14:11.424Z" },
-    { url = "https://files.pythonhosted.org/packages/21/91/9d50b433828d8e74196904e168a43abf1e6e88b2a15d47ed742456720c37/regex-2026.5.9-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:2099f7e7ff7b6aa3192312650a56e91cc091e49d50b04e4f6f8b6e28b3b27f1c", size = 289682, upload-time = "2026-05-09T23:14:13.123Z" },
-    { url = "https://files.pythonhosted.org/packages/3e/d2/b835e3cafbb9d977736912436259ff551d60919f7d7b3d37d46659c63564/regex-2026.5.9-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:ecd353045824e4477562a2ac718c25799cdaaa41f7aa925a806a8a3e6848a5b9", size = 796996, upload-time = "2026-05-09T23:14:14.923Z" },
-    { url = "https://files.pythonhosted.org/packages/2c/a6/9f992d00019166b9de01c546dd4549bc679f2a68df11b877740b0760b7c2/regex-2026.5.9-cp314-cp314-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:65c8c8c37377794bd5b2f3ebe51919042bf17aec802e23c833d89782ed0c78af", size = 866089, upload-time = "2026-05-09T23:14:17.757Z" },
-    { url = "https://files.pythonhosted.org/packages/e0/08/4d32af657e049b19cb62b02e46e38fe1518797bfb2203ee93a510b21b0dc/regex-2026.5.9-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:5b73ab8afcf66c622db143d1c6fda4e58e4d537ee4f125229ad47b1ab80f34c0", size = 911530, upload-time = "2026-05-09T23:14:20.353Z" },
-    { url = "https://files.pythonhosted.org/packages/d9/27/2af43dd1dc201d1fecefda64a45f4ad0995855b92724f795a777b402ee69/regex-2026.5.9-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0de5cf193997384ed2ca6f1cd4f78055b255d93d82d5a8cd6ba0d11c10b167e4", size = 800643, upload-time = "2026-05-09T23:14:22.265Z" },
-    { url = "https://files.pythonhosted.org/packages/a4/dd/23a249047013b5321d4a60c4d2437462086f601b061776a525e5fba2a59f/regex-2026.5.9-cp314-cp314-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:d641a8c9a61618047796d572a39a79b26167b0411d2c3031937b2fe2d081e2cf", size = 777223, upload-time = "2026-05-09T23:14:24.179Z" },
-    { url = "https://files.pythonhosted.org/packages/94/6a/e85ed9538cd19586d0465076a4578a12e093ce776d15f3f8ce92733a8dd6/regex-2026.5.9-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:24b2355ef5cc9aa5b8f07d17704face1c166fdcc2290fa7bd6e6c925655a8346", size = 785760, upload-time = "2026-05-09T23:14:26.065Z" },
-    { url = "https://files.pythonhosted.org/packages/2a/c4/f25473209438638e947c55f9156fd8f236f74169229028cc99116380868e/regex-2026.5.9-cp314-cp314-musllinux_1_2_ppc64le.whl", hash = "sha256:a24852d3c29ad9e47593593d8a247c44ccc3d0548ef12c822d6ed0810affe676", size = 860891, upload-time = "2026-05-09T23:14:28.17Z" },
-    { url = "https://files.pythonhosted.org/packages/f9/f7/f4f86e3c74419c37370e91f150ae0c2ef7d34b2e0e4cdd5da046a02e4022/regex-2026.5.9-cp314-cp314-musllinux_1_2_riscv64.whl", hash = "sha256:916714069da19329ef7de197dcbc77bb3104145c7c2c864dbfbe318f46b88b14", size = 765891, upload-time = "2026-05-09T23:14:30.06Z" },
-    { url = "https://files.pythonhosted.org/packages/26/70/704d8e13765939146b1cd0ef4e2feb71d7929727d2290f026eed10095955/regex-2026.5.9-cp314-cp314-musllinux_1_2_s390x.whl", hash = "sha256:fa411799ca8da32a8d38d020a88faa5b6f91657d284761352940ecf9f7c3bbdd", size = 851380, upload-time = "2026-05-09T23:14:32.123Z" },
-    { url = "https://files.pythonhosted.org/packages/26/29/1a13582a8460038edc38e49f64ceb0dd7c60f5caba77571f4bf6601965d9/regex-2026.5.9-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:1e6da47d679b7010ef27556b6e0f99771b744936db1792a10ceac6547ae1503e", size = 789350, upload-time = "2026-05-09T23:14:34.799Z" },
-    { url = "https://files.pythonhosted.org/packages/73/56/3dcafe34fc72e271d62ad9a291801e88a1457bb251c132f15fcc2e5aad1a/regex-2026.5.9-cp314-cp314-win32.whl", hash = "sha256:98bd73080e8756255137e1bd3f3f00295bbc5aa383c0e0f973920e9134d7c4ad", size = 272130, upload-time = "2026-05-09T23:14:36.729Z" },
-    { url = "https://files.pythonhosted.org/packages/d0/9c/02eebf0be95efe416c664db7fb8b6b05b7a0b06a7544f2884f2558b0526f/regex-2026.5.9-cp314-cp314-win_amd64.whl", hash = "sha256:ff8d372ac2acdc048d1c19916f27ee61bc5722728458ba6ca5052f2c72d51763", size = 280999, upload-time = "2026-05-09T23:14:39.126Z" },
-    { url = "https://files.pythonhosted.org/packages/70/5a/1dd1abee76cb7a846a0bcf42fdc87e5720c3c33c24f3e37814310a513d9f/regex-2026.5.9-cp314-cp314-win_arm64.whl", hash = "sha256:e1d93bf647916292e8edcec150c07ddf3dc50179ccaf770c04a7f9e452155372", size = 273500, upload-time = "2026-05-09T23:14:41.059Z" },
-    { url = "https://files.pythonhosted.org/packages/86/c1/c5f619b0057a7965cb78ec559c1d7a45ce8c99a35bea95483d64959a93d9/regex-2026.5.9-cp314-cp314t-macosx_10_13_universal2.whl", hash = "sha256:83d0ee4a57d1c87cb549e195ec300b8f0ec3a82eba66d835e4e2ed8634fe4499", size = 494269, upload-time = "2026-05-09T23:14:42.869Z" },
-    { url = "https://files.pythonhosted.org/packages/05/2c/5d01f1aee33de4bbe60c8452945bfc8477ca7c5ae4450f6bfe711036cb36/regex-2026.5.9-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:d3d7eb5c9a7f6df82ed3cfac9beb93882a5cbcb5b8b157b56cb2b3b276574ac1", size = 293954, upload-time = "2026-05-09T23:14:44.822Z" },
-    { url = "https://files.pythonhosted.org/packages/7a/fe/e8988b2ae2108c6ef71bd4aa8d87fbe257976dd0810e826cd75f701c68b6/regex-2026.5.9-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:075160bf16658e16d35233300b8453aac25de4cbea808d22348b6979668e924d", size = 292405, upload-time = "2026-05-09T23:14:47.211Z" },
-    { url = "https://files.pythonhosted.org/packages/79/34/d2b0937faa7859263f7f0a3c6b103a1296306be6952dc173d0154e9a2f49/regex-2026.5.9-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:45375819235558a4ff1c4971dc32881f022613abdb180128f5cb4768c1765a1c", size = 811855, upload-time = "2026-05-09T23:14:49.21Z" },
-    { url = "https://files.pythonhosted.org/packages/80/fe/daf53a47457a8486db66c66c01ceb9c2303eecee3f87197f1e77eb1a736d/regex-2026.5.9-cp314-cp314t-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl", hash = "sha256:ead4b163ac30a29574510cd4b3e2e985ac5290c05fc7095557d6a5f403fc31b5", size = 871189, upload-time = "2026-05-09T23:14:51.555Z" },
-    { url = "https://files.pythonhosted.org/packages/1c/75/058fc4470cbfbf57d800aff1a0022b929a3f9fa553ee10a0cdf2070eb31f/regex-2026.5.9-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:8c6e4218fbdfbcd4f6c19efca40930d24a621bf4b48cb76bc6640543bd28ef20", size = 917485, upload-time = "2026-05-09T23:14:53.633Z" },
-    { url = "https://files.pythonhosted.org/packages/88/e7/179cfda3a28bc843b5c6cfe7f79f23489c791ed95f151083803660878432/regex-2026.5.9-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:6351571c8a42b505eb555c0dc47d740d0fb66977dc142919eea6f4325b7c56a0", size = 816369, upload-time = "2026-05-09T23:14:56.198Z" },
-    { url = "https://files.pythonhosted.org/packages/41/90/6f0cc422071688266d344fca8462d787cba0a2c144acb25721f9a61ec265/regex-2026.5.9-cp314-cp314t-manylinux_2_31_riscv64.manylinux_2_39_riscv64.whl", hash = "sha256:002205cafd2a9e78c6290c7d1df277bf3277b3b7a30e0b4bb0dac2e2e3f7cb2d", size = 785869, upload-time = "2026-05-09T23:14:58.602Z" },
-    { url = "https://files.pythonhosted.org/packages/02/67/a31f1760f09c27b251ef39e9beb541f462cf977381d067faa764c2c0e393/regex-2026.5.9-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:8abd33fef90b2a9efac5557d6033ca82d1195ed3a15fea5af15ba7b463c6a63b", size = 801427, upload-time = "2026-05-09T23:15:00.642Z" },
-    { url = "https://files.pythonhosted.org/packages/e3/c4/1a80654597b6bc1e1ea0494824c31200e8a956abe290afae9b19a166a148/regex-2026.5.9-cp314-cp314t-musllinux_1_2_ppc64le.whl", hash = "sha256:31037c82eccb44b7ea2e9e221d7c01429430e989a1f4b91ea5a855f6017b509a", size = 866482, upload-time = "2026-05-09T23:15:03.384Z" },
-    { url = "https://files.pythonhosted.org/packages/d1/11/960724e06482c08466ff5611e242e86f80062949cdf6b4b9cc317b9dd93d/regex-2026.5.9-cp314-cp314t-musllinux_1_2_riscv64.whl", hash = "sha256:5604dfd046dc37eca90250fc3be938b076c8059fa772ac0ed6f499b0f0fb0415", size = 773022, upload-time = "2026-05-09T23:15:05.625Z" },
-    { url = "https://files.pythonhosted.org/packages/50/a8/a9979c3e7918280e93159ebcab5ef1a65116dd4f3bd6091be0eae4a126e8/regex-2026.5.9-cp314-cp314t-musllinux_1_2_s390x.whl", hash = "sha256:0e1b1b4e496afbb24f4a62aba855ee4f88f25578927697b340702e48c9ee6bc2", size = 856642, upload-time = "2026-05-09T23:15:07.966Z" },
-    { url = "https://files.pythonhosted.org/packages/fe/d4/a9b732f2f0072c0ab12227483abb24fffcb9f73f8a2b203df0a6d0434735/regex-2026.5.9-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:be3372b9df6ddecff6486d37e19095a7b4973137caf5512407a89f4455361f41", size = 803552, upload-time = "2026-05-09T23:15:10.215Z" },
-    { url = "https://files.pythonhosted.org/packages/d5/fe/1b3113817447a1d4155e4ac76d2e072f42c0bcba2f43fa8a0e756ea2cd91/regex-2026.5.9-cp314-cp314t-win32.whl", hash = "sha256:3ddd90103f9e5c471c49c7852ecc1fe27c7e45eb99e977aefe7caa4e779f4f58", size = 275746, upload-time = "2026-05-09T23:15:12.609Z" },
-    { url = "https://files.pythonhosted.org/packages/92/73/93d42045302636c91f2e5ef588b65b84b01428f28ec77de256b1dfdfbe5c/regex-2026.5.9-cp314-cp314t-win_amd64.whl", hash = "sha256:ca518ed29c46eecba6010b15f1b9a479314d2de409536e71b6a13aa04e3b8a77", size = 285685, upload-time = "2026-05-09T23:15:15.086Z" },
-    { url = "https://files.pythonhosted.org/packages/da/80/35b4c33c804a165a7f55289afda3ea9e3eb6d15800341a2d66455c0f1f30/regex-2026.5.9-cp314-cp314t-win_arm64.whl", hash = "sha256:5e41809d2683fcde7d5a8c87a6567ba1fb1ce0de9f31bff578de00a4b2d76daa", size = 275713, upload-time = "2026-05-09T23:15:16.98Z" },
-]
-
-[[package]]
-name = "requests"
-version = "2.34.0"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "certifi" },
-    { name = "charset-normalizer" },
-    { name = "idna" },
-    { name = "urllib3" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/43/b8/7a707d60fea4c49094e40262cc0e2ca6c768cca21587e34d3f705afec47e/requests-2.34.0.tar.gz", hash = "sha256:7d62fe92f50eb82c529b0916bb445afa1531a566fc8f35ffdc64446e771b856a", size = 142436, upload-time = "2026-05-11T19:29:51.717Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/ef/e6/e300fce5fe83c30520607a015dabd985df3251e188d234bfe9492e17a389/requests-2.34.0-py3-none-any.whl", hash = "sha256:917520a21b767485ce7c588f4ebb917c436b24a31231b44228715eaeb5a52c60", size = 73021, upload-time = "2026-05-11T19:29:49.923Z" },
-]
-
-[[package]]
-name = "rich"
-version = "15.0.0"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "markdown-it-py" },
-    { name = "pygments" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/c0/8f/0722ca900cc807c13a6a0c696dacf35430f72e0ec571c4275d2371fca3e9/rich-15.0.0.tar.gz", hash = "sha256:edd07a4824c6b40189fb7ac9bc4c52536e9780fbbfbddf6f1e2502c31b068c36", size = 230680, upload-time = "2026-04-12T08:24:00.75Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/82/3b/64d4899d73f91ba49a8c18a8ff3f0ea8f1c1d75481760df8c68ef5235bf5/rich-15.0.0-py3-none-any.whl", hash = "sha256:33bd4ef74232fb73fe9279a257718407f169c09b78a87ad3d296f548e27de0bb", size = 310654, upload-time = "2026-04-12T08:24:02.83Z" },
-]
-
-[[package]]
-name = "rpds-py"
-version = "0.30.0"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/20/af/3f2f423103f1113b36230496629986e0ef7e199d2aa8392452b484b38ced/rpds_py-0.30.0.tar.gz", hash = "sha256:dd8ff7cf90014af0c0f787eea34794ebf6415242ee1d6fa91eaba725cc441e84", size = 69469, upload-time = "2025-11-30T20:24:38.837Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/03/e7/98a2f4ac921d82f33e03f3835f5bf3a4a40aa1bfdc57975e74a97b2b4bdd/rpds_py-0.30.0-cp312-cp312-macosx_10_12_x86_64.whl", hash = "sha256:a161f20d9a43006833cd7068375a94d035714d73a172b681d8881820600abfad", size = 375086, upload-time = "2025-11-30T20:22:17.93Z" },
-    { url = "https://files.pythonhosted.org/packages/4d/a1/bca7fd3d452b272e13335db8d6b0b3ecde0f90ad6f16f3328c6fb150c889/rpds_py-0.30.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:6abc8880d9d036ecaafe709079969f56e876fcf107f7a8e9920ba6d5a3878d05", size = 359053, upload-time = "2025-11-30T20:22:19.297Z" },
-    { url = "https://files.pythonhosted.org/packages/65/1c/ae157e83a6357eceff62ba7e52113e3ec4834a84cfe07fa4b0757a7d105f/rpds_py-0.30.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ca28829ae5f5d569bb62a79512c842a03a12576375d5ece7d2cadf8abe96ec28", size = 390763, upload-time = "2025-11-30T20:22:21.661Z" },
-    { url = "https://files.pythonhosted.org/packages/d4/36/eb2eb8515e2ad24c0bd43c3ee9cd74c33f7ca6430755ccdb240fd3144c44/rpds_py-0.30.0-cp312-cp312-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:a1010ed9524c73b94d15919ca4d41d8780980e1765babf85f9a2f90d247153dd", size = 408951, upload-time = "2025-11-30T20:22:23.408Z" },
-    { url = "https://files.pythonhosted.org/packages/d6/65/ad8dc1784a331fabbd740ef6f71ce2198c7ed0890dab595adb9ea2d775a1/rpds_py-0.30.0-cp312-cp312-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:f8d1736cfb49381ba528cd5baa46f82fdc65c06e843dab24dd70b63d09121b3f", size = 514622, upload-time = "2025-11-30T20:22:25.16Z" },
-    { url = "https://files.pythonhosted.org/packages/63/8e/0cfa7ae158e15e143fe03993b5bcd743a59f541f5952e1546b1ac1b5fd45/rpds_py-0.30.0-cp312-cp312-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:d948b135c4693daff7bc2dcfc4ec57237a29bd37e60c2fabf5aff2bbacf3e2f1", size = 414492, upload-time = "2025-11-30T20:22:26.505Z" },
-    { url = "https://files.pythonhosted.org/packages/60/1b/6f8f29f3f995c7ffdde46a626ddccd7c63aefc0efae881dc13b6e5d5bb16/rpds_py-0.30.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:47f236970bccb2233267d89173d3ad2703cd36a0e2a6e92d0560d333871a3d23", size = 394080, upload-time = "2025-11-30T20:22:27.934Z" },
-    { url = "https://files.pythonhosted.org/packages/6d/d5/a266341051a7a3ca2f4b750a3aa4abc986378431fc2da508c5034d081b70/rpds_py-0.30.0-cp312-cp312-manylinux_2_31_riscv64.whl", hash = "sha256:2e6ecb5a5bcacf59c3f912155044479af1d0b6681280048b338b28e364aca1f6", size = 408680, upload-time = "2025-11-30T20:22:29.341Z" },
-    { url = "https://files.pythonhosted.org/packages/10/3b/71b725851df9ab7a7a4e33cf36d241933da66040d195a84781f49c50490c/rpds_py-0.30.0-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:a8fa71a2e078c527c3e9dc9fc5a98c9db40bcc8a92b4e8858e36d329f8684b51", size = 423589, upload-time = "2025-11-30T20:22:31.469Z" },
-    { url = "https://files.pythonhosted.org/packages/00/2b/e59e58c544dc9bd8bd8384ecdb8ea91f6727f0e37a7131baeff8d6f51661/rpds_py-0.30.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:73c67f2db7bc334e518d097c6d1e6fed021bbc9b7d678d6cc433478365d1d5f5", size = 573289, upload-time = "2025-11-30T20:22:32.997Z" },
-    { url = "https://files.pythonhosted.org/packages/da/3e/a18e6f5b460893172a7d6a680e86d3b6bc87a54c1f0b03446a3c8c7b588f/rpds_py-0.30.0-cp312-cp312-musllinux_1_2_i686.whl", hash = "sha256:5ba103fb455be00f3b1c2076c9d4264bfcb037c976167a6047ed82f23153f02e", size = 599737, upload-time = "2025-11-30T20:22:34.419Z" },
-    { url = "https://files.pythonhosted.org/packages/5c/e2/714694e4b87b85a18e2c243614974413c60aa107fd815b8cbc42b873d1d7/rpds_py-0.30.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:7cee9c752c0364588353e627da8a7e808a66873672bcb5f52890c33fd965b394", size = 563120, upload-time = "2025-11-30T20:22:35.903Z" },
-    { url = "https://files.pythonhosted.org/packages/6f/ab/d5d5e3bcedb0a77f4f613706b750e50a5a3ba1c15ccd3665ecc636c968fd/rpds_py-0.30.0-cp312-cp312-win32.whl", hash = "sha256:1ab5b83dbcf55acc8b08fc62b796ef672c457b17dbd7820a11d6c52c06839bdf", size = 223782, upload-time = "2025-11-30T20:22:37.271Z" },
-    { url = "https://files.pythonhosted.org/packages/39/3b/f786af9957306fdc38a74cef405b7b93180f481fb48453a114bb6465744a/rpds_py-0.30.0-cp312-cp312-win_amd64.whl", hash = "sha256:a090322ca841abd453d43456ac34db46e8b05fd9b3b4ac0c78bcde8b089f959b", size = 240463, upload-time = "2025-11-30T20:22:39.021Z" },
-    { url = "https://files.pythonhosted.org/packages/f3/d2/b91dc748126c1559042cfe41990deb92c4ee3e2b415f6b5234969ffaf0cc/rpds_py-0.30.0-cp312-cp312-win_arm64.whl", hash = "sha256:669b1805bd639dd2989b281be2cfd951c6121b65e729d9b843e9639ef1fd555e", size = 230868, upload-time = "2025-11-30T20:22:40.493Z" },
-    { url = "https://files.pythonhosted.org/packages/ed/dc/d61221eb88ff410de3c49143407f6f3147acf2538c86f2ab7ce65ae7d5f9/rpds_py-0.30.0-cp313-cp313-macosx_10_12_x86_64.whl", hash = "sha256:f83424d738204d9770830d35290ff3273fbb02b41f919870479fab14b9d303b2", size = 374887, upload-time = "2025-11-30T20:22:41.812Z" },
-    { url = "https://files.pythonhosted.org/packages/fd/32/55fb50ae104061dbc564ef15cc43c013dc4a9f4527a1f4d99baddf56fe5f/rpds_py-0.30.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:e7536cd91353c5273434b4e003cbda89034d67e7710eab8761fd918ec6c69cf8", size = 358904, upload-time = "2025-11-30T20:22:43.479Z" },
-    { url = "https://files.pythonhosted.org/packages/58/70/faed8186300e3b9bdd138d0273109784eea2396c68458ed580f885dfe7ad/rpds_py-0.30.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:2771c6c15973347f50fece41fc447c054b7ac2ae0502388ce3b6738cd366e3d4", size = 389945, upload-time = "2025-11-30T20:22:44.819Z" },
-    { url = "https://files.pythonhosted.org/packages/bd/a8/073cac3ed2c6387df38f71296d002ab43496a96b92c823e76f46b8af0543/rpds_py-0.30.0-cp313-cp313-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:0a59119fc6e3f460315fe9d08149f8102aa322299deaa5cab5b40092345c2136", size = 407783, upload-time = "2025-11-30T20:22:46.103Z" },
-    { url = "https://files.pythonhosted.org/packages/77/57/5999eb8c58671f1c11eba084115e77a8899d6e694d2a18f69f0ba471ec8b/rpds_py-0.30.0-cp313-cp313-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:76fec018282b4ead0364022e3c54b60bf368b9d926877957a8624b58419169b7", size = 515021, upload-time = "2025-11-30T20:22:47.458Z" },
-    { url = "https://files.pythonhosted.org/packages/e0/af/5ab4833eadc36c0a8ed2bc5c0de0493c04f6c06de223170bd0798ff98ced/rpds_py-0.30.0-cp313-cp313-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:692bef75a5525db97318e8cd061542b5a79812d711ea03dbc1f6f8dbb0c5f0d2", size = 414589, upload-time = "2025-11-30T20:22:48.872Z" },
-    { url = "https://files.pythonhosted.org/packages/b7/de/f7192e12b21b9e9a68a6d0f249b4af3fdcdff8418be0767a627564afa1f1/rpds_py-0.30.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:9027da1ce107104c50c81383cae773ef5c24d296dd11c99e2629dbd7967a20c6", size = 394025, upload-time = "2025-11-30T20:22:50.196Z" },
-    { url = "https://files.pythonhosted.org/packages/91/c4/fc70cd0249496493500e7cc2de87504f5aa6509de1e88623431fec76d4b6/rpds_py-0.30.0-cp313-cp313-manylinux_2_31_riscv64.whl", hash = "sha256:9cf69cdda1f5968a30a359aba2f7f9aa648a9ce4b580d6826437f2b291cfc86e", size = 408895, upload-time = "2025-11-30T20:22:51.87Z" },
-    { url = "https://files.pythonhosted.org/packages/58/95/d9275b05ab96556fefff73a385813eb66032e4c99f411d0795372d9abcea/rpds_py-0.30.0-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:a4796a717bf12b9da9d3ad002519a86063dcac8988b030e405704ef7d74d2d9d", size = 422799, upload-time = "2025-11-30T20:22:53.341Z" },
-    { url = "https://files.pythonhosted.org/packages/06/c1/3088fc04b6624eb12a57eb814f0d4997a44b0d208d6cace713033ff1a6ba/rpds_py-0.30.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:5d4c2aa7c50ad4728a094ebd5eb46c452e9cb7edbfdb18f9e1221f597a73e1e7", size = 572731, upload-time = "2025-11-30T20:22:54.778Z" },
-    { url = "https://files.pythonhosted.org/packages/d8/42/c612a833183b39774e8ac8fecae81263a68b9583ee343db33ab571a7ce55/rpds_py-0.30.0-cp313-cp313-musllinux_1_2_i686.whl", hash = "sha256:ba81a9203d07805435eb06f536d95a266c21e5b2dfbf6517748ca40c98d19e31", size = 599027, upload-time = "2025-11-30T20:22:56.212Z" },
-    { url = "https://files.pythonhosted.org/packages/5f/60/525a50f45b01d70005403ae0e25f43c0384369ad24ffe46e8d9068b50086/rpds_py-0.30.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:945dccface01af02675628334f7cf49c2af4c1c904748efc5cf7bbdf0b579f95", size = 563020, upload-time = "2025-11-30T20:22:58.2Z" },
-    { url = "https://files.pythonhosted.org/packages/0b/5d/47c4655e9bcd5ca907148535c10e7d489044243cc9941c16ed7cd53be91d/rpds_py-0.30.0-cp313-cp313-win32.whl", hash = "sha256:b40fb160a2db369a194cb27943582b38f79fc4887291417685f3ad693c5a1d5d", size = 223139, upload-time = "2025-11-30T20:23:00.209Z" },
-    { url = "https://files.pythonhosted.org/packages/f2/e1/485132437d20aa4d3e1d8b3fb5a5e65aa8139f1e097080c2a8443201742c/rpds_py-0.30.0-cp313-cp313-win_amd64.whl", hash = "sha256:806f36b1b605e2d6a72716f321f20036b9489d29c51c91f4dd29a3e3afb73b15", size = 240224, upload-time = "2025-11-30T20:23:02.008Z" },
-    { url = "https://files.pythonhosted.org/packages/24/95/ffd128ed1146a153d928617b0ef673960130be0009c77d8fbf0abe306713/rpds_py-0.30.0-cp313-cp313-win_arm64.whl", hash = "sha256:d96c2086587c7c30d44f31f42eae4eac89b60dabbac18c7669be3700f13c3ce1", size = 230645, upload-time = "2025-11-30T20:23:03.43Z" },
-    { url = "https://files.pythonhosted.org/packages/ff/1b/b10de890a0def2a319a2626334a7f0ae388215eb60914dbac8a3bae54435/rpds_py-0.30.0-cp313-cp313t-macosx_10_12_x86_64.whl", hash = "sha256:eb0b93f2e5c2189ee831ee43f156ed34e2a89a78a66b98cadad955972548be5a", size = 364443, upload-time = "2025-11-30T20:23:04.878Z" },
-    { url = "https://files.pythonhosted.org/packages/0d/bf/27e39f5971dc4f305a4fb9c672ca06f290f7c4e261c568f3dea16a410d47/rpds_py-0.30.0-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:922e10f31f303c7c920da8981051ff6d8c1a56207dbdf330d9047f6d30b70e5e", size = 353375, upload-time = "2025-11-30T20:23:06.342Z" },
-    { url = "https://files.pythonhosted.org/packages/40/58/442ada3bba6e8e6615fc00483135c14a7538d2ffac30e2d933ccf6852232/rpds_py-0.30.0-cp313-cp313t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:cdc62c8286ba9bf7f47befdcea13ea0e26bf294bda99758fd90535cbaf408000", size = 383850, upload-time = "2025-11-30T20:23:07.825Z" },
-    { url = "https://files.pythonhosted.org/packages/14/14/f59b0127409a33c6ef6f5c1ebd5ad8e32d7861c9c7adfa9a624fc3889f6c/rpds_py-0.30.0-cp313-cp313t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:47f9a91efc418b54fb8190a6b4aa7813a23fb79c51f4bb84e418f5476c38b8db", size = 392812, upload-time = "2025-11-30T20:23:09.228Z" },
-    { url = "https://files.pythonhosted.org/packages/b3/66/e0be3e162ac299b3a22527e8913767d869e6cc75c46bd844aa43fb81ab62/rpds_py-0.30.0-cp313-cp313t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:1f3587eb9b17f3789ad50824084fa6f81921bbf9a795826570bda82cb3ed91f2", size = 517841, upload-time = "2025-11-30T20:23:11.186Z" },
-    { url = "https://files.pythonhosted.org/packages/3d/55/fa3b9cf31d0c963ecf1ba777f7cf4b2a2c976795ac430d24a1f43d25a6ba/rpds_py-0.30.0-cp313-cp313t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:39c02563fc592411c2c61d26b6c5fe1e51eaa44a75aa2c8735ca88b0d9599daa", size = 408149, upload-time = "2025-11-30T20:23:12.864Z" },
-    { url = "https://files.pythonhosted.org/packages/60/ca/780cf3b1a32b18c0f05c441958d3758f02544f1d613abf9488cd78876378/rpds_py-0.30.0-cp313-cp313t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:51a1234d8febafdfd33a42d97da7a43f5dcb120c1060e352a3fbc0c6d36e2083", size = 383843, upload-time = "2025-11-30T20:23:14.638Z" },
-    { url = "https://files.pythonhosted.org/packages/82/86/d5f2e04f2aa6247c613da0c1dd87fcd08fa17107e858193566048a1e2f0a/rpds_py-0.30.0-cp313-cp313t-manylinux_2_31_riscv64.whl", hash = "sha256:eb2c4071ab598733724c08221091e8d80e89064cd472819285a9ab0f24bcedb9", size = 396507, upload-time = "2025-11-30T20:23:16.105Z" },
-    { url = "https://files.pythonhosted.org/packages/4b/9a/453255d2f769fe44e07ea9785c8347edaf867f7026872e76c1ad9f7bed92/rpds_py-0.30.0-cp313-cp313t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:6bdfdb946967d816e6adf9a3d8201bfad269c67efe6cefd7093ef959683c8de0", size = 414949, upload-time = "2025-11-30T20:23:17.539Z" },
-    { url = "https://files.pythonhosted.org/packages/a3/31/622a86cdc0c45d6df0e9ccb6becdba5074735e7033c20e401a6d9d0e2ca0/rpds_py-0.30.0-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:c77afbd5f5250bf27bf516c7c4a016813eb2d3e116139aed0096940c5982da94", size = 565790, upload-time = "2025-11-30T20:23:19.029Z" },
-    { url = "https://files.pythonhosted.org/packages/1c/5d/15bbf0fb4a3f58a3b1c67855ec1efcc4ceaef4e86644665fff03e1b66d8d/rpds_py-0.30.0-cp313-cp313t-musllinux_1_2_i686.whl", hash = "sha256:61046904275472a76c8c90c9ccee9013d70a6d0f73eecefd38c1ae7c39045a08", size = 590217, upload-time = "2025-11-30T20:23:20.885Z" },
-    { url = "https://files.pythonhosted.org/packages/6d/61/21b8c41f68e60c8cc3b2e25644f0e3681926020f11d06ab0b78e3c6bbff1/rpds_py-0.30.0-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:4c5f36a861bc4b7da6516dbdf302c55313afa09b81931e8280361a4f6c9a2d27", size = 555806, upload-time = "2025-11-30T20:23:22.488Z" },
-    { url = "https://files.pythonhosted.org/packages/f9/39/7e067bb06c31de48de3eb200f9fc7c58982a4d3db44b07e73963e10d3be9/rpds_py-0.30.0-cp313-cp313t-win32.whl", hash = "sha256:3d4a69de7a3e50ffc214ae16d79d8fbb0922972da0356dcf4d0fdca2878559c6", size = 211341, upload-time = "2025-11-30T20:23:24.449Z" },
-    { url = "https://files.pythonhosted.org/packages/0a/4d/222ef0b46443cf4cf46764d9c630f3fe4abaa7245be9417e56e9f52b8f65/rpds_py-0.30.0-cp313-cp313t-win_amd64.whl", hash = "sha256:f14fc5df50a716f7ece6a80b6c78bb35ea2ca47c499e422aa4463455dd96d56d", size = 225768, upload-time = "2025-11-30T20:23:25.908Z" },
-    { url = "https://files.pythonhosted.org/packages/86/81/dad16382ebbd3d0e0328776d8fd7ca94220e4fa0798d1dc5e7da48cb3201/rpds_py-0.30.0-cp314-cp314-macosx_10_12_x86_64.whl", hash = "sha256:68f19c879420aa08f61203801423f6cd5ac5f0ac4ac82a2368a9fcd6a9a075e0", size = 362099, upload-time = "2025-11-30T20:23:27.316Z" },
-    { url = "https://files.pythonhosted.org/packages/2b/60/19f7884db5d5603edf3c6bce35408f45ad3e97e10007df0e17dd57af18f8/rpds_py-0.30.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:ec7c4490c672c1a0389d319b3a9cfcd098dcdc4783991553c332a15acf7249be", size = 353192, upload-time = "2025-11-30T20:23:29.151Z" },
-    { url = "https://files.pythonhosted.org/packages/bf/c4/76eb0e1e72d1a9c4703c69607cec123c29028bff28ce41588792417098ac/rpds_py-0.30.0-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:f251c812357a3fed308d684a5079ddfb9d933860fc6de89f2b7ab00da481e65f", size = 384080, upload-time = "2025-11-30T20:23:30.785Z" },
-    { url = "https://files.pythonhosted.org/packages/72/87/87ea665e92f3298d1b26d78814721dc39ed8d2c74b86e83348d6b48a6f31/rpds_py-0.30.0-cp314-cp314-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:ac98b175585ecf4c0348fd7b29c3864bda53b805c773cbf7bfdaffc8070c976f", size = 394841, upload-time = "2025-11-30T20:23:32.209Z" },
-    { url = "https://files.pythonhosted.org/packages/77/ad/7783a89ca0587c15dcbf139b4a8364a872a25f861bdb88ed99f9b0dec985/rpds_py-0.30.0-cp314-cp314-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:3e62880792319dbeb7eb866547f2e35973289e7d5696c6e295476448f5b63c87", size = 516670, upload-time = "2025-11-30T20:23:33.742Z" },
-    { url = "https://files.pythonhosted.org/packages/5b/3c/2882bdac942bd2172f3da574eab16f309ae10a3925644e969536553cb4ee/rpds_py-0.30.0-cp314-cp314-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:4e7fc54e0900ab35d041b0601431b0a0eb495f0851a0639b6ef90f7741b39a18", size = 408005, upload-time = "2025-11-30T20:23:35.253Z" },
-    { url = "https://files.pythonhosted.org/packages/ce/81/9a91c0111ce1758c92516a3e44776920b579d9a7c09b2b06b642d4de3f0f/rpds_py-0.30.0-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:47e77dc9822d3ad616c3d5759ea5631a75e5809d5a28707744ef79d7a1bcfcad", size = 382112, upload-time = "2025-11-30T20:23:36.842Z" },
-    { url = "https://files.pythonhosted.org/packages/cf/8e/1da49d4a107027e5fbc64daeab96a0706361a2918da10cb41769244b805d/rpds_py-0.30.0-cp314-cp314-manylinux_2_31_riscv64.whl", hash = "sha256:b4dc1a6ff022ff85ecafef7979a2c6eb423430e05f1165d6688234e62ba99a07", size = 399049, upload-time = "2025-11-30T20:23:38.343Z" },
-    { url = "https://files.pythonhosted.org/packages/df/5a/7ee239b1aa48a127570ec03becbb29c9d5a9eb092febbd1699d567cae859/rpds_py-0.30.0-cp314-cp314-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:4559c972db3a360808309e06a74628b95eaccbf961c335c8fe0d590cf587456f", size = 415661, upload-time = "2025-11-30T20:23:40.263Z" },
-    { url = "https://files.pythonhosted.org/packages/70/ea/caa143cf6b772f823bc7929a45da1fa83569ee49b11d18d0ada7f5ee6fd6/rpds_py-0.30.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:0ed177ed9bded28f8deb6ab40c183cd1192aa0de40c12f38be4d59cd33cb5c65", size = 565606, upload-time = "2025-11-30T20:23:42.186Z" },
-    { url = "https://files.pythonhosted.org/packages/64/91/ac20ba2d69303f961ad8cf55bf7dbdb4763f627291ba3d0d7d67333cced9/rpds_py-0.30.0-cp314-cp314-musllinux_1_2_i686.whl", hash = "sha256:ad1fa8db769b76ea911cb4e10f049d80bf518c104f15b3edb2371cc65375c46f", size = 591126, upload-time = "2025-11-30T20:23:44.086Z" },
-    { url = "https://files.pythonhosted.org/packages/21/20/7ff5f3c8b00c8a95f75985128c26ba44503fb35b8e0259d812766ea966c7/rpds_py-0.30.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:46e83c697b1f1c72b50e5ee5adb4353eef7406fb3f2043d64c33f20ad1c2fc53", size = 553371, upload-time = "2025-11-30T20:23:46.004Z" },
-    { url = "https://files.pythonhosted.org/packages/72/c7/81dadd7b27c8ee391c132a6b192111ca58d866577ce2d9b0ca157552cce0/rpds_py-0.30.0-cp314-cp314-win32.whl", hash = "sha256:ee454b2a007d57363c2dfd5b6ca4a5d7e2c518938f8ed3b706e37e5d470801ed", size = 215298, upload-time = "2025-11-30T20:23:47.696Z" },
-    { url = "https://files.pythonhosted.org/packages/3e/d2/1aaac33287e8cfb07aab2e6b8ac1deca62f6f65411344f1433c55e6f3eb8/rpds_py-0.30.0-cp314-cp314-win_amd64.whl", hash = "sha256:95f0802447ac2d10bcc69f6dc28fe95fdf17940367b21d34e34c737870758950", size = 228604, upload-time = "2025-11-30T20:23:49.501Z" },
-    { url = "https://files.pythonhosted.org/packages/e8/95/ab005315818cc519ad074cb7784dae60d939163108bd2b394e60dc7b5461/rpds_py-0.30.0-cp314-cp314-win_arm64.whl", hash = "sha256:613aa4771c99f03346e54c3f038e4cc574ac09a3ddfb0e8878487335e96dead6", size = 222391, upload-time = "2025-11-30T20:23:50.96Z" },
-    { url = "https://files.pythonhosted.org/packages/9e/68/154fe0194d83b973cdedcdcc88947a2752411165930182ae41d983dcefa6/rpds_py-0.30.0-cp314-cp314t-macosx_10_12_x86_64.whl", hash = "sha256:7e6ecfcb62edfd632e56983964e6884851786443739dbfe3582947e87274f7cb", size = 364868, upload-time = "2025-11-30T20:23:52.494Z" },
-    { url = "https://files.pythonhosted.org/packages/83/69/8bbc8b07ec854d92a8b75668c24d2abcb1719ebf890f5604c61c9369a16f/rpds_py-0.30.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:a1d0bc22a7cdc173fedebb73ef81e07faef93692b8c1ad3733b67e31e1b6e1b8", size = 353747, upload-time = "2025-11-30T20:23:54.036Z" },
-    { url = "https://files.pythonhosted.org/packages/ab/00/ba2e50183dbd9abcce9497fa5149c62b4ff3e22d338a30d690f9af970561/rpds_py-0.30.0-cp314-cp314t-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:0d08f00679177226c4cb8c5265012eea897c8ca3b93f429e546600c971bcbae7", size = 383795, upload-time = "2025-11-30T20:23:55.556Z" },
-    { url = "https://files.pythonhosted.org/packages/05/6f/86f0272b84926bcb0e4c972262f54223e8ecc556b3224d281e6598fc9268/rpds_py-0.30.0-cp314-cp314t-manylinux_2_17_armv7l.manylinux2014_armv7l.whl", hash = "sha256:5965af57d5848192c13534f90f9dd16464f3c37aaf166cc1da1cae1fd5a34898", size = 393330, upload-time = "2025-11-30T20:23:57.033Z" },
-    { url = "https://files.pythonhosted.org/packages/cb/e9/0e02bb2e6dc63d212641da45df2b0bf29699d01715913e0d0f017ee29438/rpds_py-0.30.0-cp314-cp314t-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl", hash = "sha256:9a4e86e34e9ab6b667c27f3211ca48f73dba7cd3d90f8d5b11be56e5dbc3fb4e", size = 518194, upload-time = "2025-11-30T20:23:58.637Z" },
-    { url = "https://files.pythonhosted.org/packages/ee/ca/be7bca14cf21513bdf9c0606aba17d1f389ea2b6987035eb4f62bd923f25/rpds_py-0.30.0-cp314-cp314t-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:e5d3e6b26f2c785d65cc25ef1e5267ccbe1b069c5c21b8cc724efee290554419", size = 408340, upload-time = "2025-11-30T20:24:00.2Z" },
-    { url = "https://files.pythonhosted.org/packages/c2/c7/736e00ebf39ed81d75544c0da6ef7b0998f8201b369acf842f9a90dc8fce/rpds_py-0.30.0-cp314-cp314t-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:626a7433c34566535b6e56a1b39a7b17ba961e97ce3b80ec62e6f1312c025551", size = 383765, upload-time = "2025-11-30T20:24:01.759Z" },
-    { url = "https://files.pythonhosted.org/packages/4a/3f/da50dfde9956aaf365c4adc9533b100008ed31aea635f2b8d7b627e25b49/rpds_py-0.30.0-cp314-cp314t-manylinux_2_31_riscv64.whl", hash = "sha256:acd7eb3f4471577b9b5a41baf02a978e8bdeb08b4b355273994f8b87032000a8", size = 396834, upload-time = "2025-11-30T20:24:03.687Z" },
-    { url = "https://files.pythonhosted.org/packages/4e/00/34bcc2565b6020eab2623349efbdec810676ad571995911f1abdae62a3a0/rpds_py-0.30.0-cp314-cp314t-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:fe5fa731a1fa8a0a56b0977413f8cacac1768dad38d16b3a296712709476fbd5", size = 415470, upload-time = "2025-11-30T20:24:05.232Z" },
-    { url = "https://files.pythonhosted.org/packages/8c/28/882e72b5b3e6f718d5453bd4d0d9cf8df36fddeb4ddbbab17869d5868616/rpds_py-0.30.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:74a3243a411126362712ee1524dfc90c650a503502f135d54d1b352bd01f2404", size = 565630, upload-time = "2025-11-30T20:24:06.878Z" },
-    { url = "https://files.pythonhosted.org/packages/3b/97/04a65539c17692de5b85c6e293520fd01317fd878ea1995f0367d4532fb1/rpds_py-0.30.0-cp314-cp314t-musllinux_1_2_i686.whl", hash = "sha256:3e8eeb0544f2eb0d2581774be4c3410356eba189529a6b3e36bbbf9696175856", size = 591148, upload-time = "2025-11-30T20:24:08.445Z" },
-    { url = "https://files.pythonhosted.org/packages/85/70/92482ccffb96f5441aab93e26c4d66489eb599efdcf96fad90c14bbfb976/rpds_py-0.30.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:dbd936cde57abfee19ab3213cf9c26be06d60750e60a8e4dd85d1ab12c8b1f40", size = 556030, upload-time = "2025-11-30T20:24:10.956Z" },
-    { url = "https://files.pythonhosted.org/packages/20/53/7c7e784abfa500a2b6b583b147ee4bb5a2b3747a9166bab52fec4b5b5e7d/rpds_py-0.30.0-cp314-cp314t-win32.whl", hash = "sha256:dc824125c72246d924f7f796b4f63c1e9dc810c7d9e2355864b3c3a73d59ade0", size = 211570, upload-time = "2025-11-30T20:24:12.735Z" },
-    { url = "https://files.pythonhosted.org/packages/d0/02/fa464cdfbe6b26e0600b62c528b72d8608f5cc49f96b8d6e38c95d60c676/rpds_py-0.30.0-cp314-cp314t-win_amd64.whl", hash = "sha256:27f4b0e92de5bfbc6f86e43959e6edd1425c33b5e69aab0984a72047f2bcf1e3", size = 226532, upload-time = "2025-11-30T20:24:14.634Z" },
-]
-
-[[package]]
-name = "shellingham"
-version = "1.5.4"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/58/15/8b3609fd3830ef7b27b655beb4b4e9c62313a4e8da8c676e142cc210d58e/shellingham-1.5.4.tar.gz", hash = "sha256:8dbca0739d487e5bd35ab3ca4b36e11c4078f3a234bfce294b0a0291363404de", size = 10310, upload-time = "2023-10-24T04:13:40.426Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/e0/f9/0595336914c5619e5f28a1fb793285925a8cd4b432c9da0a987836c7f822/shellingham-1.5.4-py2.py3-none-any.whl", hash = "sha256:7ecfff8f2fd72616f7481040475a65b2bf8af90a56c89140852d1120324e8686", size = 9755, upload-time = "2023-10-24T04:13:38.866Z" },
-]
-
-[[package]]
-name = "sniffio"
-version = "1.3.1"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/a2/87/a6771e1546d97e7e041b6ae58d80074f81b7d5121207425c964ddf5cfdbd/sniffio-1.3.1.tar.gz", hash = "sha256:f4324edc670a0f49750a81b895f35c3adb843cca46f0530f79fc1babb23789dc", size = 20372, upload-time = "2024-02-25T23:20:04.057Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/e9/44/75a9c9421471a6c4805dbf2356f7c181a29c1879239abab1ea2cc8f38b40/sniffio-1.3.1-py3-none-any.whl", hash = "sha256:2f6da418d1f1e0fddd844478f41680e794e6051915791a034ff65e5f100525a2", size = 10235, upload-time = "2024-02-25T23:20:01.196Z" },
-]
-
-[[package]]
-name = "sse-starlette"
-version = "3.4.4"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "anyio" },
-    { name = "starlette" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/f7/2b/58abc2d1fd397e7dde08e947e05c884d8ef2f78d5e2588c17a12d42d6994/sse_starlette-3.4.4.tar.gz", hash = "sha256:07e0fa0460138baf25cdd5fb28683472c3995dc1642225191b3832d62526bcb0", size = 31819, upload-time = "2026-05-12T17:37:17.019Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/dc/67/805710444ea8cc75fbf70b920ed431a560c4bf9c57f7d5a3117213189399/sse_starlette-3.4.4-py3-none-any.whl", hash = "sha256:3f4dd50d8aed2771a091f3a83000323fc3844541c16b4fe585ae2420cc6df973", size = 16514, upload-time = "2026-05-12T17:37:15.601Z" },
-]
-
-[[package]]
-name = "starlette"
-version = "1.0.0"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "anyio" },
-    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/81/69/17425771797c36cded50b7fe44e850315d039f28b15901ab44839e70b593/starlette-1.0.0.tar.gz", hash = "sha256:6a4beaf1f81bb472fd19ea9b918b50dc3a77a6f2e190a12954b25e6ed5eea149", size = 2655289, upload-time = "2026-03-22T18:29:46.779Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/0b/c9/584bc9651441b4ba60cc4d557d8a547b5aff901af35bda3a4ee30c819b82/starlette-1.0.0-py3-none-any.whl", hash = "sha256:d3ec55e0bb321692d275455ddfd3df75fff145d009685eb40dc91fc66b03d38b", size = 72651, upload-time = "2026-03-22T18:29:45.111Z" },
-]
-
-[[package]]
-name = "tavily-python"
-version = "0.7.24"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "httpx" },
-    { name = "requests" },
-    { name = "tiktoken" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/92/d3/a6a9c24bfafed30b4ce3c3d685ab00806ad631c9742441f2597ec91f0002/tavily_python-0.7.24.tar.gz", hash = "sha256:6c8954193c6472231e813fe50cbd07806bd86c7228957675eb45875a44d58296", size = 27311, upload-time = "2026-04-27T17:26:50.511Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/63/ce/37e3aba0f359f540bfc57eb178f73d521161761f21e0aa28749f42750b11/tavily_python-0.7.24-py3-none-any.whl", hash = "sha256:1a750108de42c4b0b46e4c1b7b64aeaf7fad7d7bac9167927edce0081fe166c9", size = 20022, upload-time = "2026-04-27T17:26:48.885Z" },
-]
-
-[[package]]
-name = "tavilymcp"
-version = "0.1.0"
-source = { virtual = "." }
-dependencies = [
-    { name = "httpx" },
-    { name = "mcp", extra = ["cli"] },
-    { name = "openai" },
-    { name = "tavily-python" },
-]
-
-[package.metadata]
-requires-dist = [
-    { name = "httpx", specifier = ">=0.28.1" },
-    { name = "mcp", extras = ["cli"], specifier = ">=1.9.0" },
-    { name = "openai", specifier = ">=1.79.0" },
-    { name = "tavily-python" },
-]
-
-[[package]]
-name = "tiktoken"
-version = "0.12.0"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "regex" },
-    { name = "requests" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/7d/ab/4d017d0f76ec3171d469d80fc03dfbb4e48a4bcaddaa831b31d526f05edc/tiktoken-0.12.0.tar.gz", hash = "sha256:b18ba7ee2b093863978fcb14f74b3707cdc8d4d4d3836853ce7ec60772139931", size = 37806, upload-time = "2025-10-06T20:22:45.419Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/a4/85/be65d39d6b647c79800fd9d29241d081d4eeb06271f383bb87200d74cf76/tiktoken-0.12.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:b97f74aca0d78a1ff21b8cd9e9925714c15a9236d6ceacf5c7327c117e6e21e8", size = 1050728, upload-time = "2025-10-06T20:21:52.756Z" },
-    { url = "https://files.pythonhosted.org/packages/4a/42/6573e9129bc55c9bf7300b3a35bef2c6b9117018acca0dc760ac2d93dffe/tiktoken-0.12.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:2b90f5ad190a4bb7c3eb30c5fa32e1e182ca1ca79f05e49b448438c3e225a49b", size = 994049, upload-time = "2025-10-06T20:21:53.782Z" },
-    { url = "https://files.pythonhosted.org/packages/66/c5/ed88504d2f4a5fd6856990b230b56d85a777feab84e6129af0822f5d0f70/tiktoken-0.12.0-cp312-cp312-manylinux_2_28_aarch64.whl", hash = "sha256:65b26c7a780e2139e73acc193e5c63ac754021f160df919add909c1492c0fb37", size = 1129008, upload-time = "2025-10-06T20:21:54.832Z" },
-    { url = "https://files.pythonhosted.org/packages/f4/90/3dae6cc5436137ebd38944d396b5849e167896fc2073da643a49f372dc4f/tiktoken-0.12.0-cp312-cp312-manylinux_2_28_x86_64.whl", hash = "sha256:edde1ec917dfd21c1f2f8046b86348b0f54a2c0547f68149d8600859598769ad", size = 1152665, upload-time = "2025-10-06T20:21:56.129Z" },
-    { url = "https://files.pythonhosted.org/packages/a3/fe/26df24ce53ffde419a42f5f53d755b995c9318908288c17ec3f3448313a3/tiktoken-0.12.0-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:35a2f8ddd3824608b3d650a000c1ef71f730d0c56486845705a8248da00f9fe5", size = 1194230, upload-time = "2025-10-06T20:21:57.546Z" },
-    { url = "https://files.pythonhosted.org/packages/20/cc/b064cae1a0e9fac84b0d2c46b89f4e57051a5f41324e385d10225a984c24/tiktoken-0.12.0-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:83d16643edb7fa2c99eff2ab7733508aae1eebb03d5dfc46f5565862810f24e3", size = 1254688, upload-time = "2025-10-06T20:21:58.619Z" },
-    { url = "https://files.pythonhosted.org/packages/81/10/b8523105c590c5b8349f2587e2fdfe51a69544bd5a76295fc20f2374f470/tiktoken-0.12.0-cp312-cp312-win_amd64.whl", hash = "sha256:ffc5288f34a8bc02e1ea7047b8d041104791d2ddbf42d1e5fa07822cbffe16bd", size = 878694, upload-time = "2025-10-06T20:21:59.876Z" },
-    { url = "https://files.pythonhosted.org/packages/00/61/441588ee21e6b5cdf59d6870f86beb9789e532ee9718c251b391b70c68d6/tiktoken-0.12.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:775c2c55de2310cc1bc9a3ad8826761cbdc87770e586fd7b6da7d4589e13dab3", size = 1050802, upload-time = "2025-10-06T20:22:00.96Z" },
-    { url = "https://files.pythonhosted.org/packages/1f/05/dcf94486d5c5c8d34496abe271ac76c5b785507c8eae71b3708f1ad9b45a/tiktoken-0.12.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:a01b12f69052fbe4b080a2cfb867c4de12c704b56178edf1d1d7b273561db160", size = 993995, upload-time = "2025-10-06T20:22:02.788Z" },
-    { url = "https://files.pythonhosted.org/packages/a0/70/5163fe5359b943f8db9946b62f19be2305de8c3d78a16f629d4165e2f40e/tiktoken-0.12.0-cp313-cp313-manylinux_2_28_aarch64.whl", hash = "sha256:01d99484dc93b129cd0964f9d34eee953f2737301f18b3c7257bf368d7615baa", size = 1128948, upload-time = "2025-10-06T20:22:03.814Z" },
-    { url = "https://files.pythonhosted.org/packages/0c/da/c028aa0babf77315e1cef357d4d768800c5f8a6de04d0eac0f377cb619fa/tiktoken-0.12.0-cp313-cp313-manylinux_2_28_x86_64.whl", hash = "sha256:4a1a4fcd021f022bfc81904a911d3df0f6543b9e7627b51411da75ff2fe7a1be", size = 1151986, upload-time = "2025-10-06T20:22:05.173Z" },
-    { url = "https://files.pythonhosted.org/packages/a0/5a/886b108b766aa53e295f7216b509be95eb7d60b166049ce2c58416b25f2a/tiktoken-0.12.0-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:981a81e39812d57031efdc9ec59fa32b2a5a5524d20d4776574c4b4bd2e9014a", size = 1194222, upload-time = "2025-10-06T20:22:06.265Z" },
-    { url = "https://files.pythonhosted.org/packages/f4/f8/4db272048397636ac7a078d22773dd2795b1becee7bc4922fe6207288d57/tiktoken-0.12.0-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:9baf52f84a3f42eef3ff4e754a0db79a13a27921b457ca9832cf944c6be4f8f3", size = 1255097, upload-time = "2025-10-06T20:22:07.403Z" },
-    { url = "https://files.pythonhosted.org/packages/8e/32/45d02e2e0ea2be3a9ed22afc47d93741247e75018aac967b713b2941f8ea/tiktoken-0.12.0-cp313-cp313-win_amd64.whl", hash = "sha256:b8a0cd0c789a61f31bf44851defbd609e8dd1e2c8589c614cc1060940ef1f697", size = 879117, upload-time = "2025-10-06T20:22:08.418Z" },
-    { url = "https://files.pythonhosted.org/packages/ce/76/994fc868f88e016e6d05b0da5ac24582a14c47893f4474c3e9744283f1d5/tiktoken-0.12.0-cp313-cp313t-macosx_10_13_x86_64.whl", hash = "sha256:d5f89ea5680066b68bcb797ae85219c72916c922ef0fcdd3480c7d2315ffff16", size = 1050309, upload-time = "2025-10-06T20:22:10.939Z" },
-    { url = "https://files.pythonhosted.org/packages/f6/b8/57ef1456504c43a849821920d582a738a461b76a047f352f18c0b26c6516/tiktoken-0.12.0-cp313-cp313t-macosx_11_0_arm64.whl", hash = "sha256:b4e7ed1c6a7a8a60a3230965bdedba8cc58f68926b835e519341413370e0399a", size = 993712, upload-time = "2025-10-06T20:22:12.115Z" },
-    { url = "https://files.pythonhosted.org/packages/72/90/13da56f664286ffbae9dbcfadcc625439142675845baa62715e49b87b68b/tiktoken-0.12.0-cp313-cp313t-manylinux_2_28_aarch64.whl", hash = "sha256:fc530a28591a2d74bce821d10b418b26a094bf33839e69042a6e86ddb7a7fb27", size = 1128725, upload-time = "2025-10-06T20:22:13.541Z" },
-    { url = "https://files.pythonhosted.org/packages/05/df/4f80030d44682235bdaecd7346c90f67ae87ec8f3df4a3442cb53834f7e4/tiktoken-0.12.0-cp313-cp313t-manylinux_2_28_x86_64.whl", hash = "sha256:06a9f4f49884139013b138920a4c393aa6556b2f8f536345f11819389c703ebb", size = 1151875, upload-time = "2025-10-06T20:22:14.559Z" },
-    { url = "https://files.pythonhosted.org/packages/22/1f/ae535223a8c4ef4c0c1192e3f9b82da660be9eb66b9279e95c99288e9dab/tiktoken-0.12.0-cp313-cp313t-musllinux_1_2_aarch64.whl", hash = "sha256:04f0e6a985d95913cabc96a741c5ffec525a2c72e9df086ff17ebe35985c800e", size = 1194451, upload-time = "2025-10-06T20:22:15.545Z" },
-    { url = "https://files.pythonhosted.org/packages/78/a7/f8ead382fce0243cb625c4f266e66c27f65ae65ee9e77f59ea1653b6d730/tiktoken-0.12.0-cp313-cp313t-musllinux_1_2_x86_64.whl", hash = "sha256:0ee8f9ae00c41770b5f9b0bb1235474768884ae157de3beb5439ca0fd70f3e25", size = 1253794, upload-time = "2025-10-06T20:22:16.624Z" },
-    { url = "https://files.pythonhosted.org/packages/93/e0/6cc82a562bc6365785a3ff0af27a2a092d57c47d7a81d9e2295d8c36f011/tiktoken-0.12.0-cp313-cp313t-win_amd64.whl", hash = "sha256:dc2dd125a62cb2b3d858484d6c614d136b5b848976794edfb63688d539b8b93f", size = 878777, upload-time = "2025-10-06T20:22:18.036Z" },
-    { url = "https://files.pythonhosted.org/packages/72/05/3abc1db5d2c9aadc4d2c76fa5640134e475e58d9fbb82b5c535dc0de9b01/tiktoken-0.12.0-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:a90388128df3b3abeb2bfd1895b0681412a8d7dc644142519e6f0a97c2111646", size = 1050188, upload-time = "2025-10-06T20:22:19.563Z" },
-    { url = "https://files.pythonhosted.org/packages/e3/7b/50c2f060412202d6c95f32b20755c7a6273543b125c0985d6fa9465105af/tiktoken-0.12.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:da900aa0ad52247d8794e307d6446bd3cdea8e192769b56276695d34d2c9aa88", size = 993978, upload-time = "2025-10-06T20:22:20.702Z" },
-    { url = "https://files.pythonhosted.org/packages/14/27/bf795595a2b897e271771cd31cb847d479073497344c637966bdf2853da1/tiktoken-0.12.0-cp314-cp314-manylinux_2_28_aarch64.whl", hash = "sha256:285ba9d73ea0d6171e7f9407039a290ca77efcdb026be7769dccc01d2c8d7fff", size = 1129271, upload-time = "2025-10-06T20:22:22.06Z" },
-    { url = "https://files.pythonhosted.org/packages/f5/de/9341a6d7a8f1b448573bbf3425fa57669ac58258a667eb48a25dfe916d70/tiktoken-0.12.0-cp314-cp314-manylinux_2_28_x86_64.whl", hash = "sha256:d186a5c60c6a0213f04a7a802264083dea1bbde92a2d4c7069e1a56630aef830", size = 1151216, upload-time = "2025-10-06T20:22:23.085Z" },
-    { url = "https://files.pythonhosted.org/packages/75/0d/881866647b8d1be4d67cb24e50d0c26f9f807f994aa1510cb9ba2fe5f612/tiktoken-0.12.0-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:604831189bd05480f2b885ecd2d1986dc7686f609de48208ebbbddeea071fc0b", size = 1194860, upload-time = "2025-10-06T20:22:24.602Z" },
-    { url = "https://files.pythonhosted.org/packages/b3/1e/b651ec3059474dab649b8d5b69f5c65cd8fcd8918568c1935bd4136c9392/tiktoken-0.12.0-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:8f317e8530bb3a222547b85a58583238c8f74fd7a7408305f9f63246d1a0958b", size = 1254567, upload-time = "2025-10-06T20:22:25.671Z" },
-    { url = "https://files.pythonhosted.org/packages/80/57/ce64fd16ac390fafde001268c364d559447ba09b509181b2808622420eec/tiktoken-0.12.0-cp314-cp314-win_amd64.whl", hash = "sha256:399c3dd672a6406719d84442299a490420b458c44d3ae65516302a99675888f3", size = 921067, upload-time = "2025-10-06T20:22:26.753Z" },
-    { url = "https://files.pythonhosted.org/packages/ac/a4/72eed53e8976a099539cdd5eb36f241987212c29629d0a52c305173e0a68/tiktoken-0.12.0-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:c2c714c72bc00a38ca969dae79e8266ddec999c7ceccd603cc4f0d04ccd76365", size = 1050473, upload-time = "2025-10-06T20:22:27.775Z" },
-    { url = "https://files.pythonhosted.org/packages/e6/d7/0110b8f54c008466b19672c615f2168896b83706a6611ba6e47313dbc6e9/tiktoken-0.12.0-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:cbb9a3ba275165a2cb0f9a83f5d7025afe6b9d0ab01a22b50f0e74fee2ad253e", size = 993855, upload-time = "2025-10-06T20:22:28.799Z" },
-    { url = "https://files.pythonhosted.org/packages/5f/77/4f268c41a3957c418b084dd576ea2fad2e95da0d8e1ab705372892c2ca22/tiktoken-0.12.0-cp314-cp314t-manylinux_2_28_aarch64.whl", hash = "sha256:dfdfaa5ffff8993a3af94d1125870b1d27aed7cb97aa7eb8c1cefdbc87dbee63", size = 1129022, upload-time = "2025-10-06T20:22:29.981Z" },
-    { url = "https://files.pythonhosted.org/packages/4e/2b/fc46c90fe5028bd094cd6ee25a7db321cb91d45dc87531e2bdbb26b4867a/tiktoken-0.12.0-cp314-cp314t-manylinux_2_28_x86_64.whl", hash = "sha256:584c3ad3d0c74f5269906eb8a659c8bfc6144a52895d9261cdaf90a0ae5f4de0", size = 1150736, upload-time = "2025-10-06T20:22:30.996Z" },
-    { url = "https://files.pythonhosted.org/packages/28/c0/3c7a39ff68022ddfd7d93f3337ad90389a342f761c4d71de99a3ccc57857/tiktoken-0.12.0-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:54c891b416a0e36b8e2045b12b33dd66fb34a4fe7965565f1b482da50da3e86a", size = 1194908, upload-time = "2025-10-06T20:22:32.073Z" },
-    { url = "https://files.pythonhosted.org/packages/ab/0d/c1ad6f4016a3968c048545f5d9b8ffebf577774b2ede3e2e352553b685fe/tiktoken-0.12.0-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:5edb8743b88d5be814b1a8a8854494719080c28faaa1ccbef02e87354fe71ef0", size = 1253706, upload-time = "2025-10-06T20:22:33.385Z" },
-    { url = "https://files.pythonhosted.org/packages/af/df/c7891ef9d2712ad774777271d39fdef63941ffba0a9d59b7ad1fd2765e57/tiktoken-0.12.0-cp314-cp314t-win_amd64.whl", hash = "sha256:f61c0aea5565ac82e2ec50a05e02a6c44734e91b51c10510b084ea1b8e633a71", size = 920667, upload-time = "2025-10-06T20:22:34.444Z" },
-]
-
-[[package]]
-name = "tqdm"
-version = "4.67.3"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "colorama", marker = "sys_platform == 'win32'" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/09/a9/6ba95a270c6f1fbcd8dac228323f2777d886cb206987444e4bce66338dd4/tqdm-4.67.3.tar.gz", hash = "sha256:7d825f03f89244ef73f1d4ce193cb1774a8179fd96f31d7e1dcde62092b960bb", size = 169598, upload-time = "2026-02-03T17:35:53.048Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/16/e1/3079a9ff9b8e11b846c6ac5c8b5bfb7ff225eee721825310c91b3b50304f/tqdm-4.67.3-py3-none-any.whl", hash = "sha256:ee1e4c0e59148062281c49d80b25b67771a127c85fc9676d3be5f243206826bf", size = 78374, upload-time = "2026-02-03T17:35:50.982Z" },
-]
-
-[[package]]
-name = "typer"
-version = "0.25.1"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "annotated-doc" },
-    { name = "click" },
-    { name = "rich" },
-    { name = "shellingham" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/e4/51/9aed62104cea109b820bbd6c14245af756112017d309da813ef107d42e7e/typer-0.25.1.tar.gz", hash = "sha256:9616eb8853a09ffeabab1698952f33c6f29ffdbceb4eaeecf571880e8d7664cc", size = 122276, upload-time = "2026-04-30T19:32:16.964Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/3f/f9/2b3ff4e56e5fa7debfaf9eb135d0da96f3e9a1d5b27222223c7296336e5f/typer-0.25.1-py3-none-any.whl", hash = "sha256:75caa44ed46a03fb2dab8808753ffacdbfea88495e74c85a28c5eefcf5f39c89", size = 58409, upload-time = "2026-04-30T19:32:18.271Z" },
-]
-
-[[package]]
-name = "typing-extensions"
-version = "4.15.0"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/72/94/1a15dd82efb362ac84269196e94cf00f187f7ed21c242792a923cdb1c61f/typing_extensions-4.15.0.tar.gz", hash = "sha256:0cea48d173cc12fa28ecabc3b837ea3cf6f38c6d1136f85cbaaf598984861466", size = 109391, upload-time = "2025-08-25T13:49:26.313Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/18/67/36e9267722cc04a6b9f15c7f3441c2363321a3ea07da7ae0c0707beb2a9c/typing_extensions-4.15.0-py3-none-any.whl", hash = "sha256:f0fa19c6845758ab08074a0cfa8b7aecb71c999ca73d62883bc25cc018c4e548", size = 44614, upload-time = "2025-08-25T13:49:24.86Z" },
-]
-
-[[package]]
-name = "typing-inspection"
-version = "0.4.2"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "typing-extensions" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/55/e3/70399cb7dd41c10ac53367ae42139cf4b1ca5f36bb3dc6c9d33acdb43655/typing_inspection-0.4.2.tar.gz", hash = "sha256:ba561c48a67c5958007083d386c3295464928b01faa735ab8547c5692e87f464", size = 75949, upload-time = "2025-10-01T02:14:41.687Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/dc/9b/47798a6c91d8bdb567fe2698fe81e0c6b7cb7ef4d13da4114b41d239f65d/typing_inspection-0.4.2-py3-none-any.whl", hash = "sha256:4ed1cacbdc298c220f1bd249ed5287caa16f34d44ef4e9c3d0cbad5b521545e7", size = 14611, upload-time = "2025-10-01T02:14:40.154Z" },
-]
-
-[[package]]
-name = "urllib3"
-version = "2.7.0"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/53/0c/06f8b233b8fd13b9e5ee11424ef85419ba0d8ba0b3138bf360be2ff56953/urllib3-2.7.0.tar.gz", hash = "sha256:231e0ec3b63ceb14667c67be60f2f2c40a518cb38b03af60abc813da26505f4c", size = 433602, upload-time = "2026-05-07T16:13:18.596Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/7f/3e/5db95bcf282c52709639744ca2a8b149baccf648e39c8cc87553df9eae0c/urllib3-2.7.0-py3-none-any.whl", hash = "sha256:9fb4c81ebbb1ce9531cce37674bbc6f1360472bc18ca9a553ede278ef7276897", size = 131087, upload-time = "2026-05-07T16:13:17.151Z" },
-]
-
-[[package]]
-name = "uvicorn"
-version = "0.46.0"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "click" },
-    { name = "h11" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/1f/93/041fca8274050e40e6791f267d82e0e2e27dd165627bd640d3e0e378d877/uvicorn-0.46.0.tar.gz", hash = "sha256:fb9da0926999cc6cb22dc7cd71a94a632f078e6ae47ff683c5c420750fb7413d", size = 88758, upload-time = "2026-04-23T07:16:00.151Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/31/a3/5b1562db76a5a488274b2332a97199b32d0442aca0ed193697fd47786316/uvicorn-0.46.0-py3-none-any.whl", hash = "sha256:bbebbcbed972d162afca128605223022bedd345b7bc7855ce66deb31487a9048", size = 70926, upload-time = "2026-04-23T07:15:58.355Z" },
-]
diff --git a/examples/scaffolding/contrib/open_deep_research/config.example.yaml b/examples/scaffolding/contrib/open_deep_research/config.example.yaml
new file mode 100644
index 000000000000..e856fb548649
--- /dev/null
+++ b/examples/scaffolding/contrib/open_deep_research/config.example.yaml
@@ -0,0 +1,29 @@
+# ---- API keys (MCP servers with --config read these top-level keys) ----
+tavily_api_key: ""
+tavily_api_url: "https://api.tavily.com/search"
+search_api_key: ""
+search_api_url: "https://serpapi.com/search"
+jina_api_key: ""
+scraper_api_key: ""
+
+
+# ---- Per-tool MCP ----
+mcp_tools:
+  tavily_search:
+    host: "0.0.0.0"
+    port: 8087
+  fetch_webpage:
+    host: "0.0.0.0"
+    port: 8085
+  coder_mcp: # Apiary-backed Python/shell/file tools
+    host: "0.0.0.0"
+    port: 8086
+
+mcp_client_host: "127.0.0.1"
+
+# ---- Runner (run_deep_research.py, etc.) ----
+openai_api_key: "tensorrt_llm"
+base_url: "http://localhost:8000/v1"
+model: "Qwen/Qwen2.5-72B-Instruct"
+max_turn: 25
+max_tokens: 16384
diff --git a/examples/scaffolding/contrib/open_deep_research/run_deep_research.py b/examples/scaffolding/contrib/open_deep_research/run_deep_research.py
deleted file mode 100644
index 7fd97ca32062..000000000000
--- a/examples/scaffolding/contrib/open_deep_research/run_deep_research.py
+++ /dev/null
@@ -1,78 +0,0 @@
-import argparse
-import asyncio
-
-from openai import AsyncOpenAI
-
-from tensorrt_llm.scaffolding import (
-    ChatTokenCounter,
-    MCPWorker,
-    QueryCollector,
-    TaskMetricsCollector,
-    TaskTimer,
-    TRTOpenaiWorker,
-)
-from tensorrt_llm.scaffolding.contrib.open_deep_research import (
-    create_open_deep_research_scaffolding_llm,
-)
-
-
-def parse_arguments():
-    parser = argparse.ArgumentParser()
-    parser.add_argument("--openai_api_key", type=str, default="tensorrt_llm")
-    parser.add_argument("--base_url", type=str, default="http://localhost:8000/v1")
-    parser.add_argument("--model", type=str, default="Qwen3/Qwen3-30B-A3B")
-    parser.add_argument("--enable_statistics", action="store_true")
-    parser.add_argument("--enable_query_collector", action="store_true")
-    parser.add_argument("--kv_cache_hint_enabled", action="store_true")
-    return parser.parse_args()
-
-
-async def main():
-    args = parse_arguments()
-    client = AsyncOpenAI(api_key=args.openai_api_key, base_url=args.base_url)
-
-    generation_worker = TRTOpenaiWorker(client, args.model, args.kv_cache_hint_enabled)
-
-    mcp_worker = MCPWorker.init_with_urls(["http://0.0.0.0:8082/sse"])
-    await mcp_worker.init_in_asyncio_event_loop()
-
-    llm = create_open_deep_research_scaffolding_llm(
-        generation_worker,
-        mcp_worker,
-        max_tokens=16384,
-        enable_statistics=args.enable_statistics,
-        enable_query_collector=args.enable_query_collector,
-    )
-
-    prompt = """
-        From 2020 to 2050, how many elderly people will there be in Japan? What is their consumption \
-        potential across various aspects such as clothing, food, housing, and transportation? \
-        Based on population projections, elderly consumer willingness, and potential changes in their \
-        consumption habits, please produce a market size analysis report for the elderly demographic.
-    """
-
-    future = llm.generate_async(prompt)
-    result = await future.aresult()
-
-    assert result.outputs[0].text is not None
-    print("final output:" + result.outputs[0].text)
-
-    if args.enable_statistics:
-        token_counting_info = ChatTokenCounter.get_global_info()
-        print("token counting info: " + str(token_counting_info))
-        timer_info = TaskTimer.get_global_info()
-        print("timer info: " + str(timer_info))
-        TaskMetricsCollector.export_to_json("task_metrics.json")
-
-    if args.enable_query_collector:
-        QueryCollector.get_global_info()
-        print("Query info dumped to query_result.json!")
-
-    llm.shutdown()
-    generation_worker.shutdown()
-    mcp_worker.shutdown()
-    return
-
-
-if __name__ == "__main__":
-    asyncio.run(main())
diff --git a/examples/scaffolding/contrib/open_deep_research/run_open_deep_research.py b/examples/scaffolding/contrib/open_deep_research/run_open_deep_research.py
new file mode 100644
index 000000000000..cf121d09156e
--- /dev/null
+++ b/examples/scaffolding/contrib/open_deep_research/run_open_deep_research.py
@@ -0,0 +1,200 @@
+r"""Open Deep Research runner (TensorRT-LLM scaffolding).
+
+Start Apiary (if using python_interpreter), then MCP servers and LLM, then::
+
+    python examples/scaffolding/contrib/open_deep_research/run_open_deep_research.py \\
+        --config examples/scaffolding/contrib/open_deep_research/config.example.yaml --enable_tracing
+"""
+
+import argparse
+import asyncio
+import io
+from contextlib import redirect_stdout
+from datetime import datetime
+from pathlib import Path
+
+import yaml
+from openai import AsyncOpenAI
+
+from tensorrt_llm.scaffolding import (
+    MCPWorker,
+    QueryCollector,
+    TaskMetricsCollector,
+    TRTOpenaiWorker,
+)
+from tensorrt_llm.scaffolding.contrib.open_deep_research import (
+    create_open_deep_research_scaffolding_llm,
+)
+
+
+def parse_arguments():
+    parser = argparse.ArgumentParser(description="Open Deep Research with TensorRT-LLM scaffolding")
+    parser.add_argument(
+        "--config",
+        type=str,
+        default=None,
+        help="Path to config.yaml (see the shared example "
+        "examples/scaffolding/contrib/open_deep_research/config.example.yaml).",
+    )
+    parser.add_argument("--openai_api_key", type=str, default=None)
+    parser.add_argument("--base_url", type=str, default=None)
+    parser.add_argument("--model", type=str, default=None)
+    parser.add_argument("--max_tokens", type=int, default=None)
+    parser.add_argument("--max_tavily_search_chars", type=int, default=None)
+    parser.add_argument("--max_parallel_requests", type=int, default=None)
+    parser.add_argument(
+        "--enable_statistics",
+        action="store_true",
+        help="Print live task metrics and a final summary. Does not write metrics JSON.",
+    )
+    parser.add_argument("--enable_query_collector", action="store_true")
+    parser.add_argument("--enable_tracing", action="store_true")
+    parser.add_argument(
+        "--trace_output_dir",
+        type=str,
+        default=None,
+        help="Directory for trace outputs when --enable_tracing is set",
+    )
+    parser.add_argument(
+        "--prompt",
+        type=str,
+        default="From 2020 to 2050, how many elderly people will there be in Japan? "
+        "What is their consumption potential across various aspects such as clothing, "
+        "food, housing, and transportation? Based on population projections, elderly "
+        "consumer willingness, and potential changes in their consumption habits, "
+        "please produce a market size analysis report for the elderly demographic.",
+        help="Research prompt to use.",
+    )
+    return parser.parse_args()
+
+
+def _load_config(config_path: str | None) -> dict:
+    if config_path and Path(config_path).is_file():
+        with open(config_path) as f:
+            return yaml.safe_load(f) or {}
+    return {}
+
+
+_MCP_SERVICE_ORDER = (
+    ("tavily_search", 8087),
+    # ("google_scholar", 8084),
+    ("fetch_webpage", 8085),
+    ("python_interpreter", 8086),
+)
+
+
+def _mcp_sse_urls(cfg: dict) -> list[str]:
+    tools = cfg.get("mcp_tools") or {}
+    ch = str(cfg.get("mcp_client_host") or "127.0.0.1")
+    out: list[str] = []
+    for name, default_port in _MCP_SERVICE_ORDER:
+        t = tools.get(name) or {}
+        out.append(f"http://{t.get('client_host') or ch}:{int(t.get('port', default_port))}/sse")
+    return out
+
+
+def _dump_task_metrics_summary(output_dir: Path) -> None:
+    buf = io.StringIO()
+    with redirect_stdout(buf):
+        TaskMetricsCollector.print_summary()
+    summary = buf.getvalue()
+    print(summary, end="")
+
+    summary_path = output_dir / "open_deep_research.metrics.txt"
+    summary_path.write_text(summary, encoding="utf-8")
+    print(f"Task metrics summary saved to {summary_path}")
+
+
+async def main():
+    args = parse_arguments()
+    cfg = _load_config(args.config)
+
+    openai_api_key = args.openai_api_key or cfg.get("openai_api_key", "tensorrt_llm")
+    base_url = args.base_url or cfg.get("base_url", "http://localhost:8000/v1")
+    model = args.model or cfg.get("model", "Qwen3/Qwen3-30B-A3B")
+    max_tokens = (
+        args.max_tokens if args.max_tokens is not None else int(cfg.get("max_tokens", 16384))
+    )
+    max_tavily_search_chars = (
+        args.max_tavily_search_chars
+        if args.max_tavily_search_chars is not None
+        else int(cfg.get("max_tavily_search_chars", 6000))
+    )
+    max_parallel_requests = (
+        args.max_parallel_requests
+        if args.max_parallel_requests is not None
+        else int(cfg.get("max_parallel_requests", 1024))
+    )
+    trace_output_dir: Path | None = None
+    if args.enable_tracing or args.enable_statistics:
+        trace_output_dir_str = args.trace_output_dir or cfg.get("trace_output_dir")
+        if trace_output_dir_str:
+            trace_output_dir = Path(trace_output_dir_str)
+        else:
+            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+            trace_output_dir = Path(f"open_deep_research_trace_{timestamp}")
+        trace_output_dir.mkdir(parents=True, exist_ok=True)
+
+    mcp_urls = _mcp_sse_urls(cfg)
+    client = AsyncOpenAI(api_key=openai_api_key, base_url=base_url)
+
+    generation_worker = TRTOpenaiWorker(client, model)
+
+    print(f"MCP SSE URLs ({len(mcp_urls)}): {mcp_urls}")
+    if args.enable_statistics:
+        TaskMetricsCollector.reset()
+        print(
+            "Statistics enabled: "
+            f"model={model}, base_url={base_url}, max_tokens={max_tokens}, "
+            f"max_tavily_search_chars={max_tavily_search_chars}, "
+            f"max_parallel_requests={max_parallel_requests}, prompt_chars={len(args.prompt)}"
+        )
+    mcp_worker = MCPWorker.init_with_urls(mcp_urls)
+    await mcp_worker.init_in_asyncio_event_loop()
+
+    llm = create_open_deep_research_scaffolding_llm(
+        generation_worker,
+        mcp_worker,
+        max_tokens=max_tokens,
+        max_tavily_search_chars=max_tavily_search_chars,
+        max_parallel_requests=max_parallel_requests,
+        enable_statistics=args.enable_statistics,
+        enable_query_collector=args.enable_query_collector,
+        enable_tracing=args.enable_tracing,
+    )
+
+    try:
+        future = llm.generate_async(args.prompt)
+        result = await future.aresult()
+
+        assert result.outputs[0].text is not None
+        print("final output:" + result.outputs[0].text)
+
+        if args.enable_query_collector:
+            QueryCollector.get_global_info()
+            print("Query info dumped to query_result.json!")
+
+        if args.enable_tracing and result.task_collections:
+            tracer = result.task_collections.get("execution_tracer")
+            if tracer:
+                trace = tracer.export_trace()
+                assert trace_output_dir is not None
+                trace_path = trace_output_dir / "open_deep_research.trace.json"
+                full_trace_path = trace_output_dir / "open_deep_research.full.trace.json"
+                trace.save(str(trace_path))
+                trace.save(str(full_trace_path), full=True)
+                print(f"Execution trace saved to {trace_path}")
+                print(f"Full execution trace saved to {full_trace_path}")
+    finally:
+        if args.enable_statistics:
+            assert trace_output_dir is not None
+            _dump_task_metrics_summary(trace_output_dir)
+
+        llm.shutdown()
+        generation_worker.shutdown()
+        mcp_worker.shutdown()
+    return
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/scaffolding/contrib/tree_of_thought_research/README.md b/examples/scaffolding/contrib/tree_of_thought_research/README.md
new file mode 100644
index 000000000000..c4fcb7f2b148
--- /dev/null
+++ b/examples/scaffolding/contrib/tree_of_thought_research/README.md
@@ -0,0 +1,44 @@
+# Tree-of-Thought Research (scaffolding example)
+
+Research agent built on TensorRT-LLM scaffolding that explores multiple
+reasoning branches (tree of thought) using the same MCP stack as IterResearch
+and Open Deep Research: Tavily search, webpage fetch, and an optional Python
+sandbox via `coder_mcp`.
+
+Configuration (API keys, MCP host/ports, `base_url`, model name, turn/token
+limits) uses the shared example config
+`examples/scaffolding/contrib/open_deep_research/config.example.yaml`.
+IterResearch, Tree-of-Thought Research, and Open Deep Research all share the
+same layout, so there is no per-agent config file — copy the example to your
+own `config.yaml` and fill in the keys.
+
+## Prerequisites
+
+1. Serve a compatible chat model (for example with `trtllm-serve`) so `base_url`
+   points at a running OpenAI-compatible API.
+2. If you need code execution, start `coder_mcp.py` (Apiary-backed), then the
+   MCP servers.
+3. Start the MCP tools you need, passing the **same** config to each server, for
+   example `uv run … --config …/config.example.yaml`.
+4. Fill in search/scraper keys in your `config.yaml`.
+
+## Single prompt
+
+```bash
+python examples/scaffolding/contrib/tree_of_thought_research/run_tot_research.py \
+  --config examples/scaffolding/contrib/open_deep_research/config.example.yaml \
+  --enable_tracing
+```
+
+Use `--prompt "…"` to override the default question. Tree-shape knobs such as
+`--max_depth`, `--num_thoughts_per_step`, `--branch_factor`, and
+`--complete_score_threshold` control the search; CLI flags override values from
+`--config` when both are set.
+
+## Tracing (`--enable_tracing`)
+
+`--enable_tracing` turns on execution trace capture for one run. Outputs go to
+`--trace_output_dir` if provided, otherwise to a timestamped
+`tot_research_trace_<YYYYMMDD_HHMMSS>` directory. The generated `.trace.json`
+files can be consumed by the replay scripts under
+`examples/scaffolding/trace_replay`.
diff --git a/examples/scaffolding/contrib/tree_of_thought_research/run_tot_research.py b/examples/scaffolding/contrib/tree_of_thought_research/run_tot_research.py
new file mode 100644
index 000000000000..026f3885065a
--- /dev/null
+++ b/examples/scaffolding/contrib/tree_of_thought_research/run_tot_research.py
@@ -0,0 +1,190 @@
+r"""Run one Tree-of-Thought research prompt.
+
+Start the MCP servers and an OpenAI-compatible TensorRT-LLM endpoint, then run::
+
+    python examples/scaffolding/contrib/tree_of_thought_research/run_tot_research.py \
+        --config examples/scaffolding/contrib/open_deep_research/config.example.yaml --enable_tracing
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import io
+from contextlib import redirect_stdout
+from datetime import datetime
+from pathlib import Path
+
+import yaml
+from openai import AsyncOpenAI
+
+from tensorrt_llm.scaffolding import MCPWorker, TaskMetricsCollector, TRTOpenaiWorker
+from tensorrt_llm.scaffolding.contrib.tree_of_thought_research import (
+    create_tot_research_scaffolding_llm,
+)
+
+_MCP_SERVICE_ORDER = (
+    ("tavily_search", 8087),
+    ("fetch_webpage", 8085),
+    ("python_interpreter", 8086),
+)
+
+
+def parse_arguments() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Run Tree-of-Thought research on one prompt.")
+    parser.add_argument("--config", type=str, default=None, help="Path to config.yaml")
+    parser.add_argument("--openai_api_key", type=str, default=None)
+    parser.add_argument("--base_url", type=str, default=None)
+    parser.add_argument("--model", type=str, default=None)
+    parser.add_argument("--max_tokens", type=int, default=None)
+    parser.add_argument("--max_depth", type=int, default=None)
+    parser.add_argument("--num_thoughts_per_step", type=int, default=None)
+    parser.add_argument("--branch_factor", type=int, default=None)
+    parser.add_argument("--complete_score_threshold", type=float, default=None)
+    parser.add_argument("--max_tavily_search_chars", type=int, default=None)
+    parser.add_argument("--max_parallel_requests", type=int, default=None)
+    parser.add_argument("--enable_statistics", action="store_true")
+    parser.add_argument("--enable_tracing", action="store_true")
+    parser.add_argument("--trace_output_dir", type=str, default=None)
+    parser.add_argument(
+        "--prompt",
+        type=str,
+        default=(
+            "Use current sources to compare TensorRT-LLM and vLLM for serving "
+            "large language models. Include concrete differences supported by "
+            "tool observations."
+        ),
+        help="Research prompt to run.",
+    )
+    return parser.parse_args()
+
+
+def _load_config(config_path: str | None) -> dict:
+    if config_path and Path(config_path).is_file():
+        with open(config_path) as f:
+            return yaml.safe_load(f) or {}
+    return {}
+
+
+def _mcp_sse_urls(cfg: dict) -> list[str]:
+    tools = cfg.get("mcp_tools") or {}
+    client_host = str(cfg.get("mcp_client_host") or "127.0.0.1")
+    urls: list[str] = []
+    for name, default_port in _MCP_SERVICE_ORDER:
+        tool_cfg = tools.get(name) or {}
+        host = tool_cfg.get("client_host") or client_host
+        port = int(tool_cfg.get("port", default_port))
+        urls.append(f"http://{host}:{port}/sse")
+    return urls
+
+
+def _dump_task_metrics_summary(output_dir: Path) -> None:
+    buf = io.StringIO()
+    with redirect_stdout(buf):
+        TaskMetricsCollector.print_summary()
+    summary = buf.getvalue()
+    print(summary, end="")
+
+    summary_path = output_dir / "tot_research.metrics.txt"
+    summary_path.write_text(summary, encoding="utf-8")
+    print(f"Task metrics summary saved to {summary_path}")
+
+
+async def main() -> None:
+    args = parse_arguments()
+    cfg = _load_config(args.config)
+
+    openai_api_key = args.openai_api_key or cfg.get("openai_api_key", "tensorrt_llm")
+    base_url = args.base_url or cfg.get("base_url", "http://localhost:8000/v1")
+    model = args.model or cfg.get("model", "Qwen3/Qwen3-30B-A3B")
+    max_tokens = (
+        args.max_tokens if args.max_tokens is not None else int(cfg.get("max_tokens", 16384))
+    )
+    max_depth = args.max_depth if args.max_depth is not None else int(cfg.get("max_depth", 3))
+    num_thoughts = (
+        args.num_thoughts_per_step
+        if args.num_thoughts_per_step is not None
+        else int(cfg.get("num_thoughts_per_step", 3))
+    )
+    branch_factor = (
+        args.branch_factor if args.branch_factor is not None else int(cfg.get("branch_factor", 2))
+    )
+    complete_score_threshold = (
+        args.complete_score_threshold
+        if args.complete_score_threshold is not None
+        else float(cfg.get("complete_score_threshold", 8.0))
+    )
+    max_tavily_search_chars = (
+        args.max_tavily_search_chars
+        if args.max_tavily_search_chars is not None
+        else int(cfg.get("max_tavily_search_chars", 6000))
+    )
+    max_parallel_requests = (
+        args.max_parallel_requests
+        if args.max_parallel_requests is not None
+        else int(cfg.get("max_parallel_requests", 1024))
+    )
+
+    trace_output_dir: Path | None = None
+    if args.enable_tracing or args.enable_statistics:
+        trace_output_dir_str = args.trace_output_dir or cfg.get("trace_output_dir")
+        if trace_output_dir_str:
+            trace_output_dir = Path(trace_output_dir_str)
+        else:
+            timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+            trace_output_dir = Path(f"tot_research_trace_{timestamp}")
+        trace_output_dir.mkdir(parents=True, exist_ok=True)
+
+    mcp_urls = _mcp_sse_urls(cfg)
+    client = AsyncOpenAI(api_key=openai_api_key, base_url=base_url)
+    generation_worker = TRTOpenaiWorker(client, model)
+    mcp_worker = MCPWorker.init_with_urls(mcp_urls)
+    await mcp_worker.init_in_asyncio_event_loop()
+
+    print(f"MCP SSE URLs ({len(mcp_urls)}): {mcp_urls}")
+    print(f"Prompt: {args.prompt}")
+    llm = create_tot_research_scaffolding_llm(
+        generation_worker,
+        mcp_worker,
+        max_tokens=max_tokens,
+        max_depth=max_depth,
+        num_thoughts_per_step=num_thoughts,
+        branch_factor=branch_factor,
+        complete_score_threshold=complete_score_threshold,
+        max_tavily_search_chars=max_tavily_search_chars,
+        max_parallel_requests=max_parallel_requests,
+        enable_statistics=args.enable_statistics,
+        enable_tracing=args.enable_tracing,
+    )
+
+    try:
+        future = llm.generate_async(args.prompt)
+        result = await future.aresult()
+        text = result.outputs[0].text if result.outputs else ""
+        print("\n" + "=" * 80)
+        print("FINAL ANSWER:")
+        print("=" * 80)
+        print(text)
+
+        if args.enable_tracing and result.task_collections:
+            tracer = result.task_collections.get("execution_tracer")
+            if tracer:
+                trace = tracer.export_trace()
+                assert trace_output_dir is not None
+                trace_path = trace_output_dir / "tot_research.trace.json"
+                full_trace_path = trace_output_dir / "tot_research.full.trace.json"
+                trace.save(str(trace_path))
+                trace.save(str(full_trace_path), full=True)
+                print(f"Execution trace saved to {trace_path}")
+                print(f"Full execution trace saved to {full_trace_path}")
+    finally:
+        if args.enable_statistics:
+            assert trace_output_dir is not None
+            _dump_task_metrics_summary(trace_output_dir)
+        llm.shutdown()
+        generation_worker.shutdown()
+        mcp_worker.shutdown()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
diff --git a/examples/scaffolding/mcp/README.md b/examples/scaffolding/mcp/README.md
new file mode 100644
index 000000000000..4dfa81b0d1b7
--- /dev/null
+++ b/examples/scaffolding/mcp/README.md
@@ -0,0 +1,91 @@
+# MCP Servers
+
+This directory contains all MCP (Model Context Protocol) servers used by scaffolding examples.
+Each subdirectory is a standalone MCP server that can be reused across different projects.
+
+## Available Servers
+
+| Server | Description | Default Port |
+|--------|-------------|-------------|
+| `coder/` | Apiary-backed file/shell/planning tools for the Coder agent | 8083 |
+| `e2b/` | E2B sandbox for running Python code | 8081 |
+| `fetch_webpage/` | Fetch raw webpage/PDF content via Jina Reader / ScraperAPI | 8085 |
+| `google_search/` | Google web search via SerpAPI | 8083 |
+| `google_scholar/` | Google Scholar search via SerpAPI (+ web search combined) | 8084 |
+| `tavily_search/` | Tavily web search API | 8087 |
+| `weather/` | US National Weather Service alerts and forecasts | 8080 |
+| `wordllama/` | Local knowledge base search (fake Tavily replacement) | 8082 |
+
+## Quick Start
+
+Each server can be started independently. For example:
+
+> Note: some servers share the same default port (for example `coder/` and
+> `google_search/` both default to `8083`). If you run multiple servers at the
+> same time, pass `--port` to override.
+
+### Weather
+
+```bash
+cd weather
+uv run weather.py
+```
+
+### E2B Sandbox
+
+```bash
+cd e2b
+uv run e2bserver.py
+```
+
+### Tavily Search
+
+```bash
+cd tavily_search
+export TAVILY_API_KEY=<your_api_key>
+uv run tavily_search.py
+```
+
+### Coder Tools
+
+```bash
+cd coder
+uv run coder_mcp.py
+```
+
+### Google Search
+
+```bash
+cd google_search
+export SEARCH_API_KEY=<your_serpapi_key>
+uv run google_search.py
+```
+
+### Google Scholar
+
+```bash
+cd google_scholar
+export SEARCH_API_KEY=<your_serpapi_key>
+uv run google_scholar.py
+```
+
+### Fetch Webpage
+
+```bash
+cd fetch_webpage
+export JINA_API_KEY=<your_jina_key>
+uv run fetch_webpage.py
+```
+
+### WordLlama (Local KB Search)
+
+```bash
+cd wordllama
+uv run wordllama_serve.py
+```
+
+## Test
+
+```bash
+python3 mcptest.py --API_KEY YOUR_API_KEY
+```
diff --git a/examples/scaffolding/mcp/coder/README.md b/examples/scaffolding/mcp/coder/README.md
new file mode 100644
index 000000000000..6c31b1ad2a11
--- /dev/null
+++ b/examples/scaffolding/mcp/coder/README.md
@@ -0,0 +1,80 @@
+# Coder MCP Server
+
+`coder_mcp.py` is the MCP SSE server backing the Scaffolding Coder agent. Each tool call runs inside an isolated Apiary sandbox session.
+
+## Tool Surface
+
+The server exposes the tools expected by `tensorrt_llm/scaffolding/contrib/Coder/tools.py`:
+
+- `read_file`
+- `list_dir`
+- `grep_files`
+- `exec`
+- `shell`
+- `update_plan`
+- `think`
+- `complete_task`
+
+File edits go through `shell` (e.g. `sed -i`, `cat <<'EOF' > path` heredocs, `tee`).
+
+## Dependencies
+
+Install the shared Apiary Python bindings before running the server:
+
+```bash
+pip install /path/to/apiary/bindings/python
+pip install -e examples/scaffolding/mcp/coder
+```
+
+`apiary-client` supplies:
+
+- `ApiarySessionMux` for per-client session management
+- `Apiary` / `AsyncApiary` for runtime image registration
+- `apiary-mcp` reference MCP server
+- `apiary-load-swebench` CLI (and `apiary_client.swebench.resolve`) for
+  SWE-bench image-list generation
+
+## Running the Server
+
+Every Apiary session needs a Docker image name. Each SSE request can pick an image via the `image` query parameter; when it doesn't, the server falls back to `--default-image`.
+
+```bash
+python examples/scaffolding/mcp/coder/coder_mcp.py \
+    --apiary-url http://172.17.0.1:8080 \
+    --default-image ubuntu:22.04 \
+    --port 8083
+```
+
+Useful flags:
+
+- `--apiary-url`: Apiary daemon base URL
+- `--apiary-token`: Bearer token for daemon auth
+- `--mcp-token`: Bearer token required on the SSE endpoint
+- `--default-image`: Fallback Docker image for sessions when an SSE client omits the `image` query parameter (must already be registered with the daemon)
+- `--working-dir`: Default sandbox working directory
+- `--idle-timeout`: Idle session reap timeout in seconds
+
+## SSE Parameters
+
+The SSE transport lives at `/sse`, with the MCP message endpoint at
+`/messages/`.
+
+Supported query parameters:
+
+- `client_id`: Stable client identity for a persistent session
+- `image`: Docker image name for this request/session
+
+Example:
+
+```text
+http://localhost:8083/sse?client_id=my-session&image=ubuntu:22.04
+```
+
+If `image` is omitted, `coder_mcp.py` falls back to `--default-image`.
+
+## Environment Variables
+
+- `APIARY_URL`: Apiary daemon URL
+- `APIARY_API_TOKEN`: Bearer token for Apiary authentication
+- `APIARY_WORKING_DIR`: Default working directory inside the sandbox
+- `MCP_AUTH_TOKEN`: Optional bearer token required on the MCP SSE endpoint
diff --git a/examples/scaffolding/mcp/coder/coder_mcp.py b/examples/scaffolding/mcp/coder/coder_mcp.py
new file mode 100644
index 000000000000..db1204ac7b89
--- /dev/null
+++ b/examples/scaffolding/mcp/coder/coder_mcp.py
@@ -0,0 +1,617 @@
+"""Apiary-backed MCP server for the Scaffolding Coder tools."""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import contextvars
+import hmac
+import logging
+import os
+import re
+import shlex
+import uuid
+from collections import OrderedDict
+from dataclasses import dataclass, field
+
+import httpx
+import uvicorn
+from apiary_client import ApiarySessionMux, TaskResult
+from mcp.server import Server
+from mcp.server.fastmcp import FastMCP
+from mcp.server.sse import SseServerTransport
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+from starlette.routing import Mount, Route
+
+
+class _ToolFormatError(Exception):
+    """Raised by formatters when a tool's raw output can't be parsed."""
+
+
+logging.basicConfig(level=logging.INFO)
+LOGGER = logging.getLogger(__name__)
+
+mcp = FastMCP("coder_tools")
+
+_client_id: contextvars.ContextVar[str] = contextvars.ContextVar(
+    "_client_id",
+    default="stdio",
+)
+_session: ApiarySessionMux
+_mcp_auth_token: str | None = os.getenv("MCP_AUTH_TOKEN")
+
+_GREP_LINE_RE = re.compile(r"^(.*?):(\d+):(.*)$")
+
+
+@dataclass
+class PlanState:
+    current_plan: list[dict[str, str]] = field(default_factory=list)
+    explanation: str | None = None
+
+
+_plan_states: dict[str, PlanState] = {}
+
+
+def _cid() -> str:
+    return _client_id.get()
+
+
+def _q(value: str) -> str:
+    return shlex.quote(value)
+
+
+def _current_plan_state() -> PlanState:
+    cid = _cid()
+    if cid not in _plan_states:
+        _plan_states[cid] = PlanState()
+    return _plan_states[cid]
+
+
+def _format_shell_result(result: TaskResult) -> str:
+    stdout = result.stdout.rstrip("\n")
+    stderr = result.stderr.rstrip("\n")
+    parts: list[str] = []
+    if stdout:
+        parts.append(stdout)
+    if stderr:
+        parts.append(f"[stderr]\n{stderr}")
+    if result.timed_out:
+        parts.append("[timed out]")
+    body = "\n".join(parts) if parts else "(no output)"
+    return f"{body}\n\n[Exit code: {result.exit_code}]"
+
+
+def _format_http_error(error: httpx.HTTPError) -> str:
+    if isinstance(error, httpx.HTTPStatusError):
+        body = error.response.text.strip()
+        try:
+            payload = error.response.json()
+        except ValueError:
+            payload = None
+        if isinstance(payload, dict) and payload.get("error"):
+            body = str(payload["error"])
+        return body or str(error)
+    return str(error)
+
+
+def _format_tool_error(error: Exception) -> str:
+    if isinstance(error, httpx.HTTPError):
+        return f"Error: {_format_http_error(error)}"
+    return f"Error: {error}"
+
+
+def _build_read_file_command(
+    file_path: str,
+    offset: int,
+    limit: int | None,
+) -> str:
+    start = max(offset, 1)
+    line_limit = -1 if limit is None else max(limit, 0)
+    return (
+        "awk "
+        f"-v start={start} "
+        f"-v max_lines={line_limit} "
+        "'BEGIN { total = 0; printed = 0 } "
+        "{ total = NR } "
+        "NR >= start && (max_lines < 0 || printed < max_lines) { "
+        'printf "%6d|%s\\n", NR, $0; '
+        "printed++ "
+        "} "
+        'END { printf "__CODER_META__\\t%d\\t%d\\n", total, printed }'
+        f"' {_q(file_path)}"
+    )
+
+
+def _format_read_result(result: TaskResult) -> str:
+    if result.exit_code != 0:
+        raise _ToolFormatError(result.stderr.strip() or result.stdout.strip() or "read_file failed")
+
+    lines = result.stdout.splitlines()
+    if not lines or not lines[-1].startswith("__CODER_META__\t"):
+        raise _ToolFormatError("Malformed read_file response")
+
+    _, total_str, returned_str = lines[-1].split("\t")
+    content = "\n".join(lines[:-1]).rstrip("\n")
+    footer = f"[Total lines: {int(total_str)}, Lines returned: {int(returned_str)}]"
+    return f"{content}\n\n{footer}" if content else footer
+
+
+def _build_list_dir_command(dir_path: str, depth: int) -> str:
+    max_depth = max(depth, 1)
+    return f'find {_q(dir_path)} -mindepth 1 -maxdepth {max_depth} -printf "%y\\t%P\\n"'
+
+
+def _format_list_result(
+    result: TaskResult,
+    *,
+    offset: int,
+    limit: int | None,
+) -> str:
+    if result.exit_code != 0:
+        raise _ToolFormatError(result.stderr.strip() or result.stdout.strip() or "list_dir failed")
+
+    entries: list[tuple[str, str]] = []
+    for line in result.stdout.splitlines():
+        if not line:
+            continue
+        entry_type, _, name = line.partition("\t")
+        if not name:
+            continue
+        entries.append((entry_type, name))
+
+    entries.sort(key=lambda item: (_entry_sort_key(item[0]), item[1]))
+
+    start_index = max(offset, 1) - 1
+    display_offset = start_index + 1
+    end_index = None if limit is None else start_index + max(limit, 0)
+    page = entries[start_index:end_index]
+
+    rendered = "\n".join(
+        f"{display_offset + index:6d}. [{_entry_label(entry_type):5s}] {name}"
+        for index, (entry_type, name) in enumerate(page)
+    )
+    footer = f"[Total entries: {len(entries)}, Entries returned: {len(page)}]"
+    return f"{rendered}\n\n{footer}" if rendered else footer
+
+
+def _entry_sort_key(entry_type: str) -> int:
+    if entry_type == "d":
+        return 0
+    if entry_type == "f":
+        return 1
+    return 2
+
+
+def _entry_label(entry_type: str) -> str:
+    return {
+        "d": "dir",
+        "f": "file",
+        "l": "link",
+    }.get(entry_type, entry_type)
+
+
+def _build_grep_command(
+    pattern: str,
+    search_path: str,
+    include: str | None,
+) -> str:
+    parts = [
+        "grep -RIn --color=never --binary-files=without-match",
+    ]
+    if include:
+        parts.append(f"--include={_q(include)}")
+    parts.extend(
+        [
+            "--",
+            _q(pattern),
+            _q(search_path),
+            "2>/dev/null",
+        ]
+    )
+    return " ".join(parts)
+
+
+def _format_grep_result(result: TaskResult, limit: int) -> str:
+    if result.exit_code not in {0, 1}:
+        raise _ToolFormatError(
+            result.stderr.strip() or result.stdout.strip() or "grep_files failed"
+        )
+
+    grouped: OrderedDict[str, list[tuple[int, str]]] = OrderedDict()
+    for line in result.stdout.splitlines():
+        match = _GREP_LINE_RE.match(line)
+        if match is None:
+            continue
+        path, line_no, content = match.groups()
+        grouped.setdefault(path, []).append((int(line_no), content))
+
+    limited_items = list(grouped.items())[: max(limit, 0)]
+    output_lines: list[str] = []
+    for path, matches in limited_items:
+        output_lines.append(f"{path}:")
+        for line_no, content in matches[:10]:
+            truncated = content if len(content) <= 200 else content[:200] + "..."
+            output_lines.append(f"  {line_no}: {truncated}")
+        if len(matches) > 10:
+            output_lines.append(f"  ... ({len(matches) - 10} more matches)")
+        output_lines.append("")
+
+    body = "\n".join(output_lines).rstrip()
+    footer = f"[Files matched: {len(grouped)}]"
+    return f"{body}\n\n{footer}" if body else footer
+
+
+@mcp.tool()
+async def read_file(
+    file_path: str,
+    offset: int = 1,
+    limit: int | None = None,
+    mode: str = "slice",
+) -> str:
+    """Read a file with 1-indexed line numbers from the sandbox."""
+    _ = mode
+    try:
+        result = await _session.execute(_cid(), _build_read_file_command(file_path, offset, limit))
+        return _format_read_result(result)
+    except (httpx.HTTPError, _ToolFormatError) as error:
+        return _format_tool_error(error)
+
+
+@mcp.tool()
+async def list_dir(
+    dir_path: str,
+    offset: int = 1,
+    limit: int | None = None,
+    depth: int = 1,
+) -> str:
+    """List directory contents from the sandbox."""
+    try:
+        result = await _session.shell(_cid(), _build_list_dir_command(dir_path, depth))
+        return _format_list_result(result, offset=offset, limit=limit)
+    except (httpx.HTTPError, _ToolFormatError) as error:
+        return _format_tool_error(error)
+
+
+@mcp.tool()
+async def grep_files(
+    pattern: str,
+    include: str | None = None,
+    path: str | None = None,
+    limit: int = 100,
+) -> str:
+    """Search files for a regex pattern inside the sandbox."""
+    try:
+        search_path = path or "."
+        result = await _session.shell(
+            _cid(),
+            _build_grep_command(pattern, search_path, include),
+        )
+        return _format_grep_result(result, limit)
+    except (httpx.HTTPError, _ToolFormatError) as error:
+        return _format_tool_error(error)
+
+
+@mcp.tool(name="exec")
+async def exec_tool(
+    command: list[str],
+    workdir: str | None = None,
+    timeout_ms: int | None = None,
+) -> str:
+    """Execute a command array inside the sandbox without shell interpretation."""
+    if not command:
+        return "Error: command array cannot be empty"
+    try:
+        result = await _session.execute(
+            _cid(),
+            shlex.join(command),
+            timeout_ms=timeout_ms,
+            working_dir=workdir,
+        )
+        return _format_shell_result(result)
+    except httpx.HTTPError as error:
+        return _format_tool_error(error)
+
+
+@mcp.tool()
+async def shell(
+    command: str,
+    workdir: str | None = None,
+    timeout_ms: int | None = None,
+) -> str:
+    """Execute a shell command string inside the sandbox."""
+    if not command:
+        return "Error: command cannot be empty"
+    try:
+        result = await _session.shell(
+            _cid(),
+            command,
+            timeout_ms=timeout_ms,
+            working_dir=workdir,
+        )
+        return _format_shell_result(result)
+    except httpx.HTTPError as error:
+        return _format_tool_error(error)
+
+
+@mcp.tool()
+async def update_plan(
+    plan: list[dict[str, str]],
+    explanation: str | None = None,
+) -> str:
+    """Update the per-client plan state."""
+    if not plan:
+        return "Error: plan is required and cannot be empty"
+
+    valid_statuses = {"pending", "in_progress", "completed"}
+    in_progress_count = 0
+    validated_plan: list[dict[str, str]] = []
+
+    for index, item in enumerate(plan, start=1):
+        step = item.get("step")
+        status = item.get("status")
+        if not step:
+            return f"Error: plan item {index} missing 'step'"
+        if status not in valid_statuses:
+            allowed = ", ".join(sorted(valid_statuses))
+            return (
+                f"Error: plan item {index} has invalid status '{status}'. Must be one of: {allowed}"
+            )
+        if status == "in_progress":
+            in_progress_count += 1
+        validated_plan.append({"step": step, "status": status})
+
+    if in_progress_count > 1:
+        return "Error: at most one plan step can be in_progress at a time"
+
+    state = _current_plan_state()
+    state.current_plan = validated_plan
+    state.explanation = explanation
+
+    output_lines: list[str] = []
+    if explanation:
+        output_lines.extend([f"Explanation: {explanation}", ""])
+    output_lines.append("Plan:")
+    output_lines.extend(
+        f"  {index}. [{item['status']}] {item['step']}"
+        for index, item in enumerate(validated_plan, start=1)
+    )
+    completed = sum(1 for item in validated_plan if item["status"] == "completed")
+    total = len(validated_plan)
+    progress = round(completed / total * 100, 1) if total else 0.0
+    output_lines.extend(["", f"Progress: {completed}/{total} ({progress}%)"])
+    return "\n".join(output_lines)
+
+
+def _extract_code(code: str) -> str:
+    triple_match = re.search(r"```[^\n]*\n(.+?)```", code, re.DOTALL)
+    if triple_match:
+        return triple_match.group(1)
+    code_match = re.search(r"<code>(.*?)</code>", code, re.DOTALL)
+    if code_match:
+        return code_match.group(1)
+    return code
+
+
+@mcp.tool()
+async def python_interpreter(
+    code: str,
+    timeout_ms: int | None = None,
+    python_exe: str = "python3",
+) -> str:
+    """Execute Python code in the per-client sandbox."""
+    code = _extract_code(code)
+    if not code.strip():
+        return "[PythonInterpreter Error]: Empty code."
+    b64 = base64.b64encode(code.encode("utf-8")).decode("ascii")
+    py_src = f"import base64; exec(base64.b64decode({repr(b64)}).decode('utf-8'))"
+    command = f"{_q(python_exe)} -c {_q(py_src)}"
+    try:
+        result = await _session.shell(_cid(), command, timeout_ms=timeout_ms)
+    except httpx.HTTPError as error:
+        return f"[PythonInterpreter Error]: {_format_http_error(error)}"
+
+    parts: list[str] = []
+    stdout = result.stdout.rstrip("\n")
+    stderr = result.stderr.rstrip("\n")
+    if stdout:
+        parts.append(f"stdout:\n{stdout}")
+    if stderr:
+        parts.append(f"stderr:\n{stderr}")
+    if result.timed_out:
+        parts.append("[PythonInterpreter Error] TimeoutError: Execution timed out.")
+    output = "\n".join(parts)
+    return output if output.strip() else "Finished execution."
+
+
+@mcp.tool()
+async def think(thought: str) -> str:
+    """Record a thought for the current client."""
+    return f"Thought recorded: {thought}"
+
+
+@mcp.tool()
+async def complete_task(summary: str) -> str:
+    """Signal task completion for the current client."""
+    return f"Task completed: {summary}"
+
+
+def create_starlette_app(
+    mcp_server: Server,
+    *,
+    debug: bool = False,
+) -> Starlette:
+    """Create the SSE app for the Coder MCP server."""
+    sse = SseServerTransport("/messages/")
+
+    async def handle_sse(request: Request):
+        if _mcp_auth_token:
+            provided = request.headers.get("authorization", "")
+            expected = f"Bearer {_mcp_auth_token}"
+            if not hmac.compare_digest(provided.encode(), expected.encode()):
+                return JSONResponse({"error": "unauthorized"}, status_code=401)
+
+        cid = request.query_params.get("client_id") or uuid.uuid4().hex[:12]
+        image = request.query_params.get("image", "")
+        token = _client_id.set(cid)
+        try:
+            await _session.ensure_session(cid, image=image)
+        except httpx.HTTPError as error:
+            _client_id.reset(token)
+            LOGGER.warning("Failed to create sandbox for client %s: %s", cid, error)
+            return JSONResponse(
+                {"error": _format_http_error(error)},
+                status_code=502,
+            )
+
+        _session.attach(cid)
+        LOGGER.info("Client %s connected (image=%s)", cid, image or "<default>")
+        try:
+            async with sse.connect_sse(
+                request.scope,
+                request.receive,
+                request._send,
+            ) as (read_stream, write_stream):
+                try:
+                    await mcp_server.run(
+                        read_stream,
+                        write_stream,
+                        mcp_server.create_initialization_options(),
+                    )
+                finally:
+                    _session.detach(cid)
+                    LOGGER.info("Client %s disconnected", cid)
+        finally:
+            _client_id.reset(token)
+
+        return Response()
+
+    async def handle_health(_: Request):
+        return JSONResponse(
+            {
+                "status": "ok",
+                "sessions": _session.active_sessions,
+            }
+        )
+
+    async def on_startup():
+        _session.start_reaper()
+
+    async def on_shutdown():
+        await _session.shutdown()
+
+    return Starlette(
+        debug=debug,
+        routes=[
+            Route("/health", endpoint=handle_health, methods=["GET"]),
+            Route("/sse", endpoint=handle_sse, methods=["GET"]),
+            Mount("/messages/", app=sse.handle_post_message),
+        ],
+        on_startup=[on_startup],
+        on_shutdown=[on_shutdown],
+    )
+
+
+def _install_uvloop() -> bool:
+    try:
+        import uvloop  # type: ignore[import-untyped]
+
+        uvloop.install()
+        LOGGER.info("Using uvloop event loop")
+        return True
+    except ImportError:
+        LOGGER.info("uvloop not available, using default asyncio event loop")
+        return False
+
+
+def main() -> None:
+    """CLI entry point for the Coder MCP server."""
+    global _session, _mcp_auth_token
+
+    _install_uvloop()
+
+    parser = argparse.ArgumentParser(description="Run the Apiary-backed Coder MCP server")
+    parser.add_argument("--host", default="0.0.0.0", help="SSE bind host")
+    parser.add_argument("--port", type=int, default=8083, help="SSE bind port")
+    parser.add_argument(
+        "--apiary-url",
+        default=os.getenv("APIARY_URL", "http://127.0.0.1:8080"),
+        help="Apiary daemon URL",
+    )
+    parser.add_argument(
+        "--apiary-token",
+        default=os.getenv("APIARY_API_TOKEN"),
+        help="Apiary daemon bearer token",
+    )
+    parser.add_argument(
+        "--mcp-token",
+        default=os.getenv("MCP_AUTH_TOKEN"),
+        help="Require this bearer token on the MCP SSE endpoint",
+    )
+    parser.add_argument(
+        "--default-image",
+        required=True,
+        help="Fallback Docker image for sandbox sessions when an SSE client "
+        "omits the `image` query parameter (must already be registered with the daemon)",
+    )
+    parser.add_argument(
+        "--working-dir",
+        default=os.getenv("APIARY_WORKING_DIR", "/workspace"),
+        help="Default sandbox working directory",
+    )
+    parser.add_argument(
+        "--idle-timeout",
+        type=float,
+        default=300.0,
+        help="Seconds before an unconnected sandbox is reaped (default 300)",
+    )
+    parser.add_argument(
+        "--transport",
+        choices=["sse", "stdio"],
+        default="sse",
+        help="MCP transport (default: sse)",
+    )
+    parser.add_argument(
+        "--backlog",
+        type=int,
+        default=2048,
+        help="TCP listen backlog (default 2048)",
+    )
+    parser.add_argument(
+        "--limit-concurrency",
+        type=int,
+        default=500,
+        help="Max concurrent connections (default 500)",
+    )
+    args = parser.parse_args()
+
+    _session = ApiarySessionMux(
+        image=args.default_image,
+        apiary_url=args.apiary_url,
+        apiary_token=args.apiary_token,
+        working_dir=args.working_dir,
+        idle_timeout=args.idle_timeout,
+        on_client_destroy=lambda cid: _plan_states.pop(cid, None),
+    )
+    _mcp_auth_token = args.mcp_token
+
+    if args.transport == "stdio":
+        mcp.run(transport="stdio")
+        return
+
+    app = create_starlette_app(mcp._mcp_server, debug=True)
+    LOGGER.info("Starting Coder MCP server on %s:%s", args.host, args.port)
+    uvicorn.run(
+        app,
+        host=args.host,
+        port=args.port,
+        backlog=args.backlog,
+        limit_concurrency=args.limit_concurrency,
+        timeout_keep_alive=30,
+        log_level="info",
+    )
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/scaffolding/mcp/coder/pyproject.toml b/examples/scaffolding/mcp/coder/pyproject.toml
new file mode 100644
index 000000000000..7c21ea2e4463
--- /dev/null
+++ b/examples/scaffolding/mcp/coder/pyproject.toml
@@ -0,0 +1,19 @@
+[project]
+name = "coder-mcp"
+version = "0.1.0"
+description = "MCP Server for Coder agent tools (file operations, shell commands, etc.)"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "apiary-client",
+    "mcp>=1.0.0",
+    "uvicorn>=0.30.0",
+    "starlette>=0.37.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["."]
diff --git a/examples/scaffolding/contrib/mcp/e2b/.env b/examples/scaffolding/mcp/e2b/.env.example
similarity index 100%
rename from examples/scaffolding/contrib/mcp/e2b/.env
rename to examples/scaffolding/mcp/e2b/.env.example
diff --git a/examples/scaffolding/contrib/mcp/e2b/README.md b/examples/scaffolding/mcp/e2b/README.md
similarity index 100%
rename from examples/scaffolding/contrib/mcp/e2b/README.md
rename to examples/scaffolding/mcp/e2b/README.md
diff --git a/examples/scaffolding/contrib/mcp/e2b/e2bserver.py b/examples/scaffolding/mcp/e2b/e2bserver.py
similarity index 72%
rename from examples/scaffolding/contrib/mcp/e2b/e2bserver.py
rename to examples/scaffolding/mcp/e2b/e2bserver.py
index 1818619fcaf6..435a15584137 100644
--- a/examples/scaffolding/contrib/mcp/e2b/e2bserver.py
+++ b/examples/scaffolding/mcp/e2b/e2bserver.py
@@ -28,11 +28,15 @@ class ToolSchema(BaseModel):
 
 @mcp.tool()
 async def run_code(code: str) -> str:
-    """Run python code in a secure sandbox by E2B. Using the Jupyter Notebook syntax. Response include 1.results, the function return value. 2.stdout, the standard output. 3.stderr, the standard error.
+    """Run python code in a secure sandbox by E2B.
+
+    Uses the Jupyter Notebook syntax. Response includes 1.results, the
+    function return value. 2.stdout, the standard output. 3.stderr, the
+    standard error.
+
     Args:
         code: string in Jupyter Notebook syntax.
     """
-
     sbx = Sandbox()
     execution = sbx.run_code(code)
     logger.info(f"Execution: {execution}")
@@ -46,17 +50,15 @@ async def run_code(code: str) -> str:
     return f"{result}"
 
 
-def create_starlette_app(mcp_server: Server,
-                         *,
-                         debug: bool = False) -> Starlette:
+def create_starlette_app(mcp_server: Server, *, debug: bool = False) -> Starlette:
     """Create a Starlette application that can server the provided mcp server with SSE."""
     sse = SseServerTransport("/messages/")
 
     async def handle_sse(request: Request) -> None:
         async with sse.connect_sse(
-                request.scope,
-                request.receive,
-                request._send,  # noqa: SLF001
+            request.scope,
+            request.receive,
+            request._send,  # noqa: SLF001
         ) as (read_stream, write_stream):
             await mcp_server.run(
                 read_stream,
@@ -78,12 +80,9 @@ async def handle_sse(request: Request) -> None:
 
     import argparse
 
-    parser = argparse.ArgumentParser(description='Run MCP SSE-based server')
-    parser.add_argument('--host', default='0.0.0.0', help='Host to bind to')
-    parser.add_argument('--port',
-                        type=int,
-                        default=8081,
-                        help='Port to listen on')
+    parser = argparse.ArgumentParser(description="Run MCP SSE-based server")
+    parser.add_argument("--host", default="0.0.0.0", help="Host to bind to")
+    parser.add_argument("--port", type=int, default=8081, help="Port to listen on")
     args = parser.parse_args()
 
     # Bind SSE request handling to MCP server
diff --git a/examples/scaffolding/contrib/mcp/e2b/main.py b/examples/scaffolding/mcp/e2b/main.py
similarity index 100%
rename from examples/scaffolding/contrib/mcp/e2b/main.py
rename to examples/scaffolding/mcp/e2b/main.py
diff --git a/examples/scaffolding/contrib/mcp/e2b/pyproject.toml b/examples/scaffolding/mcp/e2b/pyproject.toml
similarity index 100%
rename from examples/scaffolding/contrib/mcp/e2b/pyproject.toml
rename to examples/scaffolding/mcp/e2b/pyproject.toml
diff --git a/examples/scaffolding/mcp/fetch_webpage/__init__.py b/examples/scaffolding/mcp/fetch_webpage/__init__.py
new file mode 100644
index 000000000000..0fe85f86aad7
--- /dev/null
+++ b/examples/scaffolding/mcp/fetch_webpage/__init__.py
@@ -0,0 +1,3 @@
+from .visit_controller import VisitController, VisitTask
+
+__all__ = ["VisitController", "VisitTask"]
diff --git a/examples/scaffolding/mcp/fetch_webpage/fetch_webpage.py b/examples/scaffolding/mcp/fetch_webpage/fetch_webpage.py
new file mode 100644
index 000000000000..7f435be0c689
--- /dev/null
+++ b/examples/scaffolding/mcp/fetch_webpage/fetch_webpage.py
@@ -0,0 +1,218 @@
+"""MCP server: fetch webpage/PDF via Jina Reader / ScraperAPI."""
+
+import asyncio
+import logging
+import os
+import tempfile
+import uuid
+from datetime import datetime
+from pathlib import Path
+
+import httpx
+import uvicorn
+import yaml
+from mcp.server import Server
+from mcp.server.fastmcp import FastMCP
+from mcp.server.sse import SseServerTransport
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.responses import Response
+from starlette.routing import Mount, Route
+
+logging.basicConfig(level=logging.INFO)
+LOGGER = logging.getLogger(__name__)
+
+mcp = FastMCP("fetch_webpage")
+
+
+def _mcp_bind_from_cfg(cfg: dict, service: str, default_port: int) -> tuple[str, int]:
+    svc = (cfg.get("mcp_tools") or {}).get(service) or {}
+    return str(svc.get("host", "0.0.0.0")), int(svc.get("port", default_port))
+
+
+def _load_config(config_path: str | None = None) -> dict:
+    cfg = {}
+    if config_path and Path(config_path).is_file():
+        with open(config_path) as f:
+            cfg = yaml.safe_load(f) or {}
+        LOGGER.info("Loaded config from %s", config_path)
+
+    def _get(yaml_key: str, env_key: str, default: str = "") -> str:
+        return str(cfg.get(yaml_key, "") or os.getenv(env_key, default))
+
+    mcp_host, mcp_port = _mcp_bind_from_cfg(cfg, "fetch_webpage", 8085)
+    return {
+        "jina_api_key": _get("jina_api_key", "JINA_API_KEY"),
+        "scraper_api_key": _get("scraper_api_key", "SCRAPER_API_KEY"),
+        "mcp_host": mcp_host,
+        "mcp_port": mcp_port,
+    }
+
+
+_CFG: dict = {
+    "jina_api_key": os.getenv("JINA_API_KEY", ""),
+    "scraper_api_key": os.getenv("SCRAPER_API_KEY", ""),
+}
+
+
+async def _fetch_via_jina(client: httpx.AsyncClient, url: str) -> str:
+    if not _CFG["jina_api_key"]:
+        try:
+            headers = {"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"}
+            resp = await client.get(url, headers=headers, timeout=30)
+            resp.raise_for_status()
+            return resp.text
+        except Exception:
+            return ""
+    headers = {"Authorization": f"Bearer {_CFG['jina_api_key']}"}
+    for attempt in range(3):
+        try:
+            resp = await client.get(f"https://r.jina.ai/{url}", headers=headers, timeout=60)
+            if resp.status_code == 200:
+                return resp.text
+        except Exception:
+            pass
+        await asyncio.sleep(2)
+    return ""
+
+
+async def _fetch_via_scraper(client: httpx.AsyncClient, url: str) -> tuple[str, str]:
+    if not _CFG["scraper_api_key"]:
+        return ("html", "")
+    params = {
+        "api_key": _CFG["scraper_api_key"],
+        "url": url,
+        "device_type": "desktop",
+        "country_code": "us",
+        "output_format": "markdown",
+    }
+    for attempt in range(3):
+        try:
+            resp = await client.get("https://api.scraperapi.com/", params=params, timeout=60)
+            resp.raise_for_status()
+            ct = resp.headers.get("Content-Type", "").lower()
+            if "pdf" in ct:
+                tmp_dir = tempfile.mkdtemp(prefix="fetch_webpage_pdf_")
+                ts = datetime.now().strftime("%Y%m%d_%H%M%S")
+                path = os.path.join(tmp_dir, f"doc_{ts}_{uuid.uuid4()}.pdf")
+                with open(path, "wb") as f:
+                    f.write(resp.content)
+                return ("pdf", path)
+            if "text" in ct:
+                return ("html", resp.text)
+            return ("other", "")
+        except Exception:
+            if attempt == 2:
+                return ("other", "")
+            await asyncio.sleep(1)
+    return ("other", "")
+
+
+def _parse_pdf(pdf_path: str) -> str:
+    try:
+        import fitz  # PyMuPDF
+    except ImportError:
+        return "[PDF Parser Error]: PyMuPDF not installed. pip install pymupdf"
+    try:
+        doc = fitz.open(pdf_path)
+        parts = []
+        for page_num in range(len(doc)):
+            page = doc[page_num]
+            text = page.get_text()
+            if text.strip():
+                parts.append(f"## Page {page_num + 1}\n\n{text}")
+        doc.close()
+        return "\n\n".join(parts)
+    except Exception as e:
+        return f"[PDF Parser Error]: {e}"
+
+
+async def _fetch_single_url(client: httpx.AsyncClient, url: str, parse_type: str) -> str:
+    LOGGER.info("[fetch_webpage] start url=%s parse_type=%s", url, parse_type)
+    content_type, content = await _fetch_via_scraper(client, url)
+    LOGGER.info(
+        "[fetch_webpage] scraper result url=%s content_type=%s chars=%d",
+        url,
+        content_type,
+        len(content),
+    )
+    if content_type == "pdf":
+        parsed_content = await asyncio.to_thread(_parse_pdf, content)
+        LOGGER.info(
+            "[fetch_webpage] parsed pdf url=%s chars=%d",
+            url,
+            len(parsed_content),
+        )
+        return parsed_content
+    if content_type == "html" and content:
+        return content
+    content = await _fetch_via_jina(client, url)
+    LOGGER.info("[fetch_webpage] jina result url=%s chars=%d", url, len(content))
+    if content:
+        return content
+    return f"[fetch_webpage] Failed to fetch: {url}"
+
+
+@mcp.tool()
+async def fetch_webpage(url: list[str], parse_type: str = "html") -> str:
+    """Fetch raw webpage/PDF content via Jina Reader / ScraperAPI."""
+    LOGGER.info("[fetch_webpage] request url_count=%d parse_type=%s", len(url), parse_type)
+    async with httpx.AsyncClient() as client:
+        tasks = [_fetch_single_url(client, u, parse_type) for u in url]
+        results = await asyncio.gather(*tasks)
+    joined_result = "\n=======\n".join(results)
+    LOGGER.info(
+        "[fetch_webpage] response url_count=%d result_chars=%d per_url_chars=%s",
+        len(url),
+        len(joined_result),
+        [len(result) for result in results],
+    )
+    return joined_result
+
+
+def create_starlette_app(mcp_server: Server, *, debug: bool = False) -> Starlette:
+    sse = SseServerTransport("/messages/")
+
+    async def handle_sse(request: Request) -> Response:
+        async with sse.connect_sse(
+            request.scope,
+            request.receive,
+            request._send,  # noqa: SLF001
+        ) as (read_stream, write_stream):
+            await mcp_server.run(
+                read_stream,
+                write_stream,
+                mcp_server.create_initialization_options(),
+            )
+        return Response()
+
+    return Starlette(
+        debug=debug,
+        routes=[
+            Route("/sse", endpoint=handle_sse),
+            Mount("/messages/", app=sse.handle_post_message),
+        ],
+    )
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Fetch Webpage MCP SSE-based server")
+    parser.add_argument(
+        "--config", type=str, default=None, help="Path to config.yaml (API keys, endpoints)"
+    )
+    parser.add_argument("--host", default=None, help="Host to bind to (overrides config)")
+    parser.add_argument(
+        "--port", type=int, default=None, help="Port to listen on (overrides config)"
+    )
+    args = parser.parse_args()
+
+    _CFG.update(_load_config(args.config))
+
+    host = args.host or _CFG.get("mcp_host", "0.0.0.0")
+    port = args.port or _CFG.get("mcp_port", 8085)
+
+    mcp_server = mcp._mcp_server  # noqa: WPS437
+    starlette_app = create_starlette_app(mcp_server, debug=True)
+    uvicorn.run(starlette_app, host=host, port=port)
diff --git a/examples/scaffolding/mcp/fetch_webpage/pyproject.toml b/examples/scaffolding/mcp/fetch_webpage/pyproject.toml
new file mode 100644
index 000000000000..51e836c29878
--- /dev/null
+++ b/examples/scaffolding/mcp/fetch_webpage/pyproject.toml
@@ -0,0 +1,13 @@
+[project]
+name = "fetch-webpage-mcp"
+version = "0.1.0"
+description = "MCP server for fetching webpage/PDF content via Jina Reader / ScraperAPI"
+requires-python = ">=3.12"
+dependencies = [
+    "httpx>=0.28.1",
+    "mcp[cli]>=1.9.0",
+    "pymupdf>=1.24.0",
+    "pyyaml>=6.0",
+    "uvicorn>=0.30.0",
+    "starlette>=0.38.0",
+]
diff --git a/examples/scaffolding/mcp/fetch_webpage/visit_controller.py b/examples/scaffolding/mcp/fetch_webpage/visit_controller.py
new file mode 100644
index 000000000000..815c509d41a0
--- /dev/null
+++ b/examples/scaffolding/mcp/fetch_webpage/visit_controller.py
@@ -0,0 +1,259 @@
+import json
+import logging
+import re
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import List, Optional
+
+from tensorrt_llm.scaffolding import system_prompt
+from tensorrt_llm.scaffolding.controller import Controller
+from tensorrt_llm.scaffolding.task import ChatTask, MCPCallTask, SystemMessage, Task, UserMessage
+
+_VISIT_MAX_PROMPT_CHARS = 15000
+_VISIT_PDF_MAX_PROMPT_CHARS = 10000
+_VISIT_PDF_MAX_LINES = 200
+_VISIT_MAX_RESULT_CHARS = 2000
+_VISIT_EXTRACTOR_SYSTEM_PROMPT = system_prompt(
+    """You process webpage content and a user goal to extract relevant information.
+
+## **Task Guidelines**
+1. **Content Scanning for Rational**:
+    Locate the **specific sections/data** directly related to the user's goal within the webpage content
+2. **Key Extraction for Evidence**:
+    Identify and extract the **most relevant information** from the content, you never miss any important information,
+    output the **full original context** of the content as far as possible, it can be more than three paragraphs.
+3. **Summary Output for Summary**:
+    Organize into a concise paragraph with logical flow,
+    prioritizing clarity and judge the contribution of the information to the goal.
+
+**Final Output Format using JSON format has "rational", "evidence", "summary" fields**
+""",
+    name="fetch_webpage.visit_extractor_system_prompt",
+)
+
+_VISIT_EXTRACTOR_USER_PROMPT = """## **Webpage Content**
+{webpage_content}
+
+## **User Goal**
+{goal}
+"""
+
+LOGGER = logging.getLogger(__name__)
+
+
+def _looks_like_raw_pdf(content: str) -> bool:
+    text = content.lstrip()
+    if text.startswith("%PDF-"):
+        return True
+    pdf_markers = (" obj", "endobj", "stream", "endstream", "/Type/Page")
+    hit_count = sum(1 for marker in pdf_markers if marker in content)
+    return hit_count >= 3
+
+
+def _truncate_with_notice(content: str, max_chars: int, source: str) -> str:
+    if len(content) <= max_chars:
+        return content
+    truncated = content[:max_chars]
+    return (
+        f"{truncated}\n\n"
+        f"[truncated {source}: kept first {max_chars} characters to control prompt size]"
+    )
+
+
+def _sanitize_text(content: str) -> str:
+    sanitized_chars: List[str] = []
+    for ch in content:
+        if ch in ("\n", "\t"):
+            sanitized_chars.append(ch)
+            continue
+        if ch.isprintable():
+            sanitized_chars.append(ch)
+    return "".join(sanitized_chars)
+
+
+def _extract_pdf_text_lines(raw_content: str) -> List[str]:
+    syntax_line = re.compile(
+        r"^\s*(\d+\s+\d+\s+obj|endobj|stream|endstream|xref|trailer|%%EOF)\s*$"
+    )
+    mostly_punct = re.compile(r"^[^A-Za-z0-9\u4e00-\u9fff\u3040-\u30ff]+$")
+    extracted: List[str] = []
+    for raw_line in raw_content.splitlines():
+        line = raw_line.strip()
+        if not line:
+            continue
+        if syntax_line.match(line):
+            continue
+        if mostly_punct.match(line):
+            continue
+        line = re.sub(r"\s+", " ", line)
+        if len(line) < 8:
+            continue
+        if len(line) > 300:
+            line = line[:300]
+        extracted.append(line)
+        if len(extracted) >= _VISIT_PDF_MAX_LINES:
+            break
+    return extracted
+
+
+def _prepare_webpage_content(raw_content: str, parse_type: str, max_webpage_tokens: int) -> str:
+    # Keep prompt size conservative because binary/garbled text can explode tokenization.
+    max_chars = min(max_webpage_tokens * 2, _VISIT_MAX_PROMPT_CHARS)
+    is_pdf = parse_type == "pdf" or _looks_like_raw_pdf(raw_content)
+    if is_pdf:
+        pdf_max_chars = min(max_webpage_tokens, _VISIT_PDF_MAX_PROMPT_CHARS)
+        extracted_lines = _extract_pdf_text_lines(raw_content)
+        if extracted_lines:
+            structured_text = _sanitize_text("\n".join(extracted_lines))
+            return _truncate_with_notice(
+                structured_text,
+                pdf_max_chars,
+                "PDF structured extraction",
+            )
+        return _truncate_with_notice(_sanitize_text(raw_content), pdf_max_chars, "raw PDF content")
+    return _truncate_with_notice(_sanitize_text(raw_content), max_chars, "webpage content")
+
+
+def _get_last_assistant_message_content(chat_task: ChatTask) -> Optional[str]:
+    for message in reversed(chat_task.messages):
+        if getattr(message, "role", None) == "assistant":
+            return message.content or ""
+    return None
+
+
+def _parse_json_output(raw: str) -> Optional[dict]:
+    if not raw:
+        return None
+    triple_match = re.search(r"```json\s*\n(.*?)\n```", raw, re.DOTALL)
+    if triple_match:
+        json_str = triple_match.group(1)
+        try:
+            return json.loads(json_str)
+        except json.JSONDecodeError:
+            return None
+    try:
+        return json.loads(raw)
+    except json.JSONDecodeError:
+        return None
+
+
+@dataclass
+class VisitTask(Task):
+    """URLs, goal, and parse_type for Visit (fetch + summarize)."""
+
+    urls: Optional[list] = field(default=None)
+    goal: Optional[str] = field(default=None)
+    parse_type: str = field(default="html")
+    result_str: Optional[str] = field(default=None)
+
+
+class VisitController(Controller):
+    """MCP ``fetch_webpage``, truncate, then LLM summarization."""
+
+    class WorkerTag(Enum):
+        TOOL_CALL = "visit_tool_call"
+
+    def __init__(self, generation_controller: Controller, max_webpage_tokens: int = 48000):
+        super().__init__()
+        self.generation_controller = generation_controller
+        self.max_webpage_tokens = max_webpage_tokens
+
+    def clone(self):
+        return VisitController(
+            generation_controller=self.generation_controller.clone(),
+            max_webpage_tokens=self.max_webpage_tokens,
+        )
+
+    def process(self, tasks: List[Task], **kwargs):
+        assert len(tasks) == 1 and isinstance(tasks[0], VisitTask), (
+            "VisitController only supports a single VisitTask"
+        )
+        visit_task = tasks[0]
+        LOGGER.warning(
+            "[visit] fetch_webpage start: url_count=%d parse_type=%s max_webpage_tokens=%d",
+            len(visit_task.urls or []),
+            visit_task.parse_type,
+            self.max_webpage_tokens,
+        )
+
+        mcp_task = MCPCallTask.create_mcptask(
+            tool_call_id="visit_fetch",
+            tool_name="fetch_webpage",
+            args=json.dumps(
+                {
+                    "url": visit_task.urls,
+                    "parse_type": visit_task.parse_type,
+                }
+            ),
+            worker_tag=self.WorkerTag.TOOL_CALL,
+        )
+        yield [mcp_task]
+
+        raw_content = mcp_task.result_str or ""
+        LOGGER.warning(
+            "[visit] fetch_webpage raw result: chars=%d parse_type=%s",
+            len(raw_content),
+            visit_task.parse_type,
+        )
+        if not raw_content:
+            visit_task.result_str = "[visit] Failed to fetch webpage content."
+            return
+
+        prepared_content = _prepare_webpage_content(
+            raw_content,
+            visit_task.parse_type,
+            self.max_webpage_tokens,
+        )
+        LOGGER.warning(
+            "[visit] prepared webpage content: raw_chars=%d prepared_chars=%d parse_type=%s",
+            len(raw_content),
+            len(prepared_content),
+            visit_task.parse_type,
+        )
+        if not prepared_content.strip():
+            visit_task.result_str = "[visit] Failed to prepare webpage content for summarization."
+            return
+
+        user_prompt = _VISIT_EXTRACTOR_USER_PROMPT.format(
+            webpage_content=prepared_content,
+            goal=visit_task.goal,
+        )
+        LOGGER.warning(
+            "[visit] extractor prompt: user_chars=%d goal_chars=%d prepared_chars=%d",
+            len(user_prompt),
+            len(visit_task.goal or ""),
+            len(prepared_content),
+        )
+        chat_task = ChatTask.create_from_messages(
+            [
+                SystemMessage(content=_VISIT_EXTRACTOR_SYSTEM_PROMPT),
+                UserMessage(user_prompt),
+            ]
+        )
+        yield from self.generation_controller.process([chat_task])
+
+        urls_str = ", ".join(visit_task.urls) if visit_task.urls else "unknown"
+        llm_response = _get_last_assistant_message_content(chat_task)
+        if llm_response is None:
+            visit_task.result_str = (
+                f"[visit] Failed to summarize webpage content from '{urls_str}': "
+                "no assistant response was produced."
+            )
+            return
+
+        parsed = _parse_json_output(llm_response)
+        useful_info = (
+            f"The useful information in '{urls_str}' for user goal '{visit_task.goal}':\n\n"
+        )
+
+        if parsed and "evidence" in parsed and "summary" in parsed:
+            useful_info += f"Evidence in page:\n{parsed['evidence']}\n\n"
+            useful_info += f"Summary:\n{parsed['summary']}\n"
+        else:
+            useful_info += llm_response
+
+        visit_task.result_str = _truncate_with_notice(
+            useful_info,
+            _VISIT_MAX_RESULT_CHARS,
+            "visit summary",
+        )
diff --git a/examples/scaffolding/mcp/google_scholar/google_scholar.py b/examples/scaffolding/mcp/google_scholar/google_scholar.py
new file mode 100644
index 000000000000..0b352d2ee00e
--- /dev/null
+++ b/examples/scaffolding/mcp/google_scholar/google_scholar.py
@@ -0,0 +1,203 @@
+"""MCP server: Google Scholar + web search via SerpAPI."""
+
+import asyncio
+import logging
+import os
+from pathlib import Path
+
+import httpx
+import uvicorn
+import yaml
+from mcp.server import Server
+from mcp.server.fastmcp import FastMCP
+from mcp.server.sse import SseServerTransport
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.responses import Response
+from starlette.routing import Mount, Route
+
+logging.basicConfig(level=logging.INFO)
+LOGGER = logging.getLogger(__name__)
+
+mcp = FastMCP("google_scholar")
+
+
+def _mcp_bind_from_cfg(cfg: dict, service: str, default_port: int) -> tuple[str, int]:
+    svc = (cfg.get("mcp_tools") or {}).get(service) or {}
+    return str(svc.get("host", "0.0.0.0")), int(svc.get("port", default_port))
+
+
+def _load_config(config_path: str | None = None) -> dict:
+    cfg = {}
+    if config_path and Path(config_path).is_file():
+        with open(config_path) as f:
+            cfg = yaml.safe_load(f) or {}
+        LOGGER.info("Loaded config from %s", config_path)
+
+    def _get(yaml_key: str, env_key: str, default: str = "") -> str:
+        return str(cfg.get(yaml_key, "") or os.getenv(env_key, default))
+
+    mcp_host, mcp_port = _mcp_bind_from_cfg(cfg, "google_scholar", 8084)
+    return {
+        "search_api_key": _get("search_api_key", "SEARCH_API_KEY"),
+        "search_api_url": _get("search_api_url", "SEARCH_API_URL", "https://serpapi.com/search"),
+        "mcp_host": mcp_host,
+        "mcp_port": mcp_port,
+    }
+
+
+_CFG: dict = {
+    "search_api_key": os.getenv("SEARCH_API_KEY", ""),
+    "search_api_url": os.getenv("SEARCH_API_URL", "https://serpapi.com/search"),
+}
+
+
+async def _search_single(client: httpx.AsyncClient, query: str) -> str:
+    contains_chinese = any("\u4e00" <= c <= "\u9fff" for c in query)
+    params = {
+        "api_key": _CFG["search_api_key"],
+        "q": query,
+        "num": 10,
+        "hl": "zh-CN" if contains_chinese else "en",
+        "gl": "CN" if contains_chinese else "US",
+    }
+    for attempt in range(3):
+        try:
+            resp = await client.get(_CFG["search_api_url"], params=params, timeout=30)
+            resp.raise_for_status()
+            results = resp.json()
+            organic = results.get("organic_results", [])
+            if not organic:
+                if attempt < 2:
+                    await asyncio.sleep(1)
+                    continue
+                return f"No results found for '{query}'."
+            snippets = []
+            for idx, page in enumerate(organic, 1):
+                title = page.get("title", "No title")
+                link = page.get("link", "")
+                snippet = page.get("snippet", "")
+                date = page.get("date", "")
+                source = page.get("source", "")
+                date_str = f"\nDate published: {date}" if date else ""
+                source_str = f"\nSource: {source}" if source else ""
+                snippet_str = f"\n{snippet}" if snippet else ""
+                snippets.append(f"{idx}. [{title}]({link}){date_str}{source_str}{snippet_str}")
+            return (
+                f"A Google search for '{query}' found "
+                f"{len(snippets)} results:\n\n## Web Results\n" + "\n\n".join(snippets)
+            )
+        except Exception as e:
+            if attempt == 2:
+                return f"Search failed for '{query}': {e}"
+            await asyncio.sleep(2)
+    return f"No results found for '{query}'."
+
+
+async def _scholar_single(client: httpx.AsyncClient, query: str) -> str:
+    params = {
+        "api_key": _CFG["search_api_key"],
+        "engine": "google_scholar",
+        "q": query,
+        "num": 10,
+        "hl": "en",
+    }
+    for attempt in range(3):
+        try:
+            resp = await client.get(_CFG["search_api_url"], params=params, timeout=30)
+            resp.raise_for_status()
+            results = resp.json()
+            organic = results.get("organic_results", [])
+            if not organic:
+                return f"No scholar results for '{query}'."
+            snippets = []
+            for idx, page in enumerate(organic, 1):
+                title = page.get("title", "No title")
+                link = page.get("link", "no available link")
+                snippet = page.get("snippet", "")
+                pub_info = page.get("publication_info", {}).get("summary", "")
+                cited_by = page.get("inline_links", {}).get("cited_by", {}).get("total", "")
+                resources = page.get("resources", [])
+                pdf_link = ""
+                for res in resources:
+                    if res.get("file_format") == "PDF":
+                        pdf_link = res.get("link", "")
+                        break
+                link_info = f"pdfUrl: {pdf_link}" if pdf_link else f"link: {link}"
+                pub_str = f"\npublicationInfo: {pub_info}" if pub_info else ""
+                cite_str = f"\ncitedBy: {cited_by}" if cited_by else ""
+                snippet_str = f"\n{snippet}" if snippet else ""
+                snippets.append(f"{idx}. [{title}]({link_info}){pub_str}{cite_str}{snippet_str}")
+            return (
+                f"A Google Scholar search for '{query}' found "
+                f"{len(snippets)} results:\n\n## Scholar Results\n" + "\n\n".join(snippets)
+            )
+        except Exception as e:
+            if attempt == 2:
+                return f"Scholar search failed for '{query}': {e}"
+            await asyncio.sleep(1)
+    return f"No scholar results for '{query}'."
+
+
+@mcp.tool()
+async def google_scholar(query: list[str]) -> str:
+    """Scholar search via SerpAPI + web search combined results."""
+    if not _CFG["search_api_key"]:
+        return "[google_scholar] Error: search_api_key not configured."
+    async with httpx.AsyncClient() as client:
+        scholar_tasks = [_scholar_single(client, q) for q in query]
+        search_tasks = [_search_single(client, q) for q in query]
+        all_results = await asyncio.gather(*(scholar_tasks + search_tasks))
+    n = len(query)
+    combined = []
+    for i in range(n):
+        combined.append(f"{all_results[i]}\n\n{all_results[n + i]}")
+    return "\n=======\n".join(combined)
+
+
+def create_starlette_app(mcp_server: Server, *, debug: bool = False) -> Starlette:
+    sse = SseServerTransport("/messages/")
+
+    async def handle_sse(request: Request) -> Response:
+        async with sse.connect_sse(
+            request.scope,
+            request.receive,
+            request._send,  # noqa: SLF001
+        ) as (read_stream, write_stream):
+            await mcp_server.run(
+                read_stream,
+                write_stream,
+                mcp_server.create_initialization_options(),
+            )
+        return Response()
+
+    return Starlette(
+        debug=debug,
+        routes=[
+            Route("/sse", endpoint=handle_sse),
+            Mount("/messages/", app=sse.handle_post_message),
+        ],
+    )
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Google Scholar MCP SSE-based server")
+    parser.add_argument(
+        "--config", type=str, default=None, help="Path to config.yaml (API keys, endpoints)"
+    )
+    parser.add_argument("--host", default=None, help="Host to bind to (overrides config)")
+    parser.add_argument(
+        "--port", type=int, default=None, help="Port to listen on (overrides config)"
+    )
+    args = parser.parse_args()
+
+    _CFG.update(_load_config(args.config))
+
+    host = args.host or _CFG.get("mcp_host", "0.0.0.0")
+    port = args.port or _CFG.get("mcp_port", 8084)
+
+    mcp_server = mcp._mcp_server  # noqa: WPS437
+    starlette_app = create_starlette_app(mcp_server, debug=True)
+    uvicorn.run(starlette_app, host=host, port=port)
diff --git a/examples/scaffolding/mcp/google_scholar/pyproject.toml b/examples/scaffolding/mcp/google_scholar/pyproject.toml
new file mode 100644
index 000000000000..27163b8156d2
--- /dev/null
+++ b/examples/scaffolding/mcp/google_scholar/pyproject.toml
@@ -0,0 +1,12 @@
+[project]
+name = "google-scholar-mcp"
+version = "0.1.0"
+description = "MCP server for Google Scholar search via SerpAPI"
+requires-python = ">=3.12"
+dependencies = [
+    "httpx>=0.28.1",
+    "mcp[cli]>=1.9.0",
+    "pyyaml>=6.0",
+    "uvicorn>=0.30.0",
+    "starlette>=0.38.0",
+]
diff --git a/examples/scaffolding/mcp/google_search/google_search.py b/examples/scaffolding/mcp/google_search/google_search.py
new file mode 100644
index 000000000000..dd30897c9933
--- /dev/null
+++ b/examples/scaffolding/mcp/google_search/google_search.py
@@ -0,0 +1,153 @@
+"""MCP server: Google web search via SerpAPI."""
+
+import asyncio
+import logging
+import os
+from pathlib import Path
+
+import httpx
+import uvicorn
+import yaml
+from mcp.server import Server
+from mcp.server.fastmcp import FastMCP
+from mcp.server.sse import SseServerTransport
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.responses import Response
+from starlette.routing import Mount, Route
+
+logging.basicConfig(level=logging.INFO)
+LOGGER = logging.getLogger(__name__)
+
+mcp = FastMCP("google_search")
+
+
+def _mcp_bind_from_cfg(cfg: dict, service: str, default_port: int) -> tuple[str, int]:
+    svc = (cfg.get("mcp_tools") or {}).get(service) or {}
+    return str(svc.get("host", "0.0.0.0")), int(svc.get("port", default_port))
+
+
+def _load_config(config_path: str | None = None) -> dict:
+    cfg = {}
+    if config_path and Path(config_path).is_file():
+        with open(config_path) as f:
+            cfg = yaml.safe_load(f) or {}
+        LOGGER.info("Loaded config from %s", config_path)
+
+    def _get(yaml_key: str, env_key: str, default: str = "") -> str:
+        return str(cfg.get(yaml_key, "") or os.getenv(env_key, default))
+
+    mcp_host, mcp_port = _mcp_bind_from_cfg(cfg, "google_search", 8083)
+    return {
+        "search_api_key": _get("search_api_key", "SEARCH_API_KEY"),
+        "search_api_url": _get("search_api_url", "SEARCH_API_URL", "https://serpapi.com/search"),
+        "mcp_host": mcp_host,
+        "mcp_port": mcp_port,
+    }
+
+
+_CFG: dict = {
+    "search_api_key": os.getenv("SEARCH_API_KEY", ""),
+    "search_api_url": os.getenv("SEARCH_API_URL", "https://serpapi.com/search"),
+}
+
+
+async def _search_single(client: httpx.AsyncClient, query: str) -> str:
+    contains_chinese = any("\u4e00" <= c <= "\u9fff" for c in query)
+    params = {
+        "api_key": _CFG["search_api_key"],
+        "q": query,
+        "num": 10,
+        "hl": "zh-CN" if contains_chinese else "en",
+        "gl": "CN" if contains_chinese else "US",
+    }
+    for attempt in range(3):
+        try:
+            resp = await client.get(_CFG["search_api_url"], params=params, timeout=30)
+            resp.raise_for_status()
+            results = resp.json()
+            organic = results.get("organic_results", [])
+            if not organic:
+                if attempt < 2:
+                    await asyncio.sleep(1)
+                    continue
+                return f"No results found for '{query}'."
+            snippets = []
+            for idx, page in enumerate(organic, 1):
+                title = page.get("title", "No title")
+                link = page.get("link", "")
+                snippet = page.get("snippet", "")
+                date = page.get("date", "")
+                source = page.get("source", "")
+                date_str = f"\nDate published: {date}" if date else ""
+                source_str = f"\nSource: {source}" if source else ""
+                snippet_str = f"\n{snippet}" if snippet else ""
+                snippets.append(f"{idx}. [{title}]({link}){date_str}{source_str}{snippet_str}")
+            return (
+                f"A Google search for '{query}' found "
+                f"{len(snippets)} results:\n\n## Web Results\n" + "\n\n".join(snippets)
+            )
+        except Exception as e:
+            if attempt == 2:
+                return f"Search failed for '{query}': {e}"
+            await asyncio.sleep(2)
+    return f"No results found for '{query}'."
+
+
+@mcp.tool()
+async def google_search(query: list[str]) -> str:
+    """Web search via SerpAPI. Returns formatted results for each query."""
+    if not _CFG["search_api_key"]:
+        return "[google_search] Error: search_api_key not configured."
+    async with httpx.AsyncClient() as client:
+        tasks = [_search_single(client, q) for q in query]
+        results = await asyncio.gather(*tasks)
+    return "\n=======\n".join(results)
+
+
+def create_starlette_app(mcp_server: Server, *, debug: bool = False) -> Starlette:
+    sse = SseServerTransport("/messages/")
+
+    async def handle_sse(request: Request) -> Response:
+        async with sse.connect_sse(
+            request.scope,
+            request.receive,
+            request._send,  # noqa: SLF001
+        ) as (read_stream, write_stream):
+            await mcp_server.run(
+                read_stream,
+                write_stream,
+                mcp_server.create_initialization_options(),
+            )
+        return Response()
+
+    return Starlette(
+        debug=debug,
+        routes=[
+            Route("/sse", endpoint=handle_sse),
+            Mount("/messages/", app=sse.handle_post_message),
+        ],
+    )
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Google Search MCP SSE-based server")
+    parser.add_argument(
+        "--config", type=str, default=None, help="Path to config.yaml (API keys, endpoints)"
+    )
+    parser.add_argument("--host", default=None, help="Host to bind to (overrides config)")
+    parser.add_argument(
+        "--port", type=int, default=None, help="Port to listen on (overrides config)"
+    )
+    args = parser.parse_args()
+
+    _CFG.update(_load_config(args.config))
+
+    host = args.host or _CFG.get("mcp_host", "0.0.0.0")
+    port = args.port or _CFG.get("mcp_port", 8083)
+
+    mcp_server = mcp._mcp_server  # noqa: WPS437
+    starlette_app = create_starlette_app(mcp_server, debug=True)
+    uvicorn.run(starlette_app, host=host, port=port)
diff --git a/examples/scaffolding/mcp/google_search/pyproject.toml b/examples/scaffolding/mcp/google_search/pyproject.toml
new file mode 100644
index 000000000000..fd396317795f
--- /dev/null
+++ b/examples/scaffolding/mcp/google_search/pyproject.toml
@@ -0,0 +1,12 @@
+[project]
+name = "google-search-mcp"
+version = "0.1.0"
+description = "MCP server for Google web search via SerpAPI"
+requires-python = ">=3.12"
+dependencies = [
+    "httpx>=0.28.1",
+    "mcp[cli]>=1.9.0",
+    "pyyaml>=6.0",
+    "uvicorn>=0.30.0",
+    "starlette>=0.38.0",
+]
diff --git a/examples/scaffolding/contrib/mcp/mcptest.py b/examples/scaffolding/mcp/mcptest.py
similarity index 65%
rename from examples/scaffolding/contrib/mcp/mcptest.py
rename to examples/scaffolding/mcp/mcptest.py
index 6c4919d60e69..15518887fe6f 100644
--- a/examples/scaffolding/contrib/mcp/mcptest.py
+++ b/examples/scaffolding/mcp/mcptest.py
@@ -4,23 +4,22 @@
 from openai import AsyncOpenAI
 
 from tensorrt_llm.scaffolding import OpenaiWorker, ScaffoldingLlm
-from tensorrt_llm.scaffolding.contrib.mcp import (ChatTask, MCPController,
-                                                  MCPWorker, chat_handler)
+from tensorrt_llm.scaffolding.contrib.mcp import ChatTask, MCPController, MCPWorker, chat_handler
 
 
 def parse_arguments():
     parser = argparse.ArgumentParser()
     parser.add_argument(
-        '--base_url',
+        "--base_url",
         type=str,
         default="https://dashscope.aliyuncs.com/compatible-mode/v1",
     )
     parser.add_argument(
-        '--model',
+        "--model",
         type=str,
         default="qwen-plus-latest",
     )
-    parser.add_argument('--API_KEY', type=str)
+    parser.add_argument("--API_KEY", type=str)
     args = parser.parse_args()
     return args
 
@@ -29,13 +28,14 @@ async def main():
     args = parse_arguments()
     prompts = [
         # "What's the weather like today in LA?"
-        # 'Solve the problem with running python code: What is the number of Fibonacci array 20th element? The array goes like 0,1,1,2,3...'
+        # 'Solve the problem with running python code: What is the number of'
+        # ' Fibonacci array 20th element? The array goes like 0,1,1,2,3...'
         # 'Which game won TGA Best Action Game and Players Voice awards in 2024?'
-        'What was the score of the NBA playoffs game 7 between the Thunder and the Nuggets in 2025?'
+        "What was the score of the NBA playoffs game 7 between the Thunder and the Nuggets in 2025?"
     ]
     API_KEY = args.API_KEY
     urls = [
-        #"http://0.0.0.0:8080/sse", "http://0.0.0.0:8081/sse",
+        # "http://0.0.0.0:8080/sse", "http://0.0.0.0:8081/sse",
         "http://0.0.0.0:8082/sse"
     ]
     print(f"API_KEY {API_KEY}")
@@ -47,25 +47,22 @@ async def main():
     prototype_controller = MCPController()
     llm = ScaffoldingLlm(
         prototype_controller,
-        {
-            MCPController.WorkerTag.GENERATION: qwen_worker,
-            MCPController.WorkerTag.MCP: mcp_worker
-        },
+        {MCPController.WorkerTag.GENERATION: qwen_worker, MCPController.WorkerTag.MCP: mcp_worker},
     )
 
     future = llm.generate_async(prompts[0])
     result = await future.aresult()
     print(f"\nresult is {result.outputs[0].text}\n")
 
-    print(f'main shutting down...')
+    print("main shutting down...")
     llm.shutdown()
-    print(f'worker shutting down...')
+    print("worker shutting down...")
     qwen_worker.shutdown()
     await mcp_worker.shutdown()
 
-    print(f'main shut down done')
+    print("main shut down done")
     return
 
 
-if __name__ == '__main__':
+if __name__ == "__main__":
     asyncio.run(main())
diff --git a/examples/scaffolding/mcp/tavily_search/__init__.py b/examples/scaffolding/mcp/tavily_search/__init__.py
new file mode 100644
index 000000000000..3f1a3e6448ef
--- /dev/null
+++ b/examples/scaffolding/mcp/tavily_search/__init__.py
@@ -0,0 +1,3 @@
+from .tavily_controller import TavilyController, TavilyTask
+
+__all__ = ["TavilyController", "TavilyTask"]
diff --git a/examples/scaffolding/mcp/tavily_search/pyproject.toml b/examples/scaffolding/mcp/tavily_search/pyproject.toml
new file mode 100644
index 000000000000..15bc89da8713
--- /dev/null
+++ b/examples/scaffolding/mcp/tavily_search/pyproject.toml
@@ -0,0 +1,12 @@
+[project]
+name = "tavily-search-mcp"
+version = "0.1.0"
+description = "MCP server for web search via Tavily API"
+requires-python = ">=3.12"
+dependencies = [
+    "httpx>=0.28.1",
+    "mcp[cli]>=1.9.0",
+    "pyyaml>=6.0",
+    "uvicorn>=0.30.0",
+    "starlette>=0.38.0",
+]
diff --git a/examples/scaffolding/mcp/tavily_search/tavily_controller.py b/examples/scaffolding/mcp/tavily_search/tavily_controller.py
new file mode 100644
index 000000000000..f5d9e9a59e61
--- /dev/null
+++ b/examples/scaffolding/mcp/tavily_search/tavily_controller.py
@@ -0,0 +1,149 @@
+import json
+import logging
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import List, Optional
+
+from tensorrt_llm.scaffolding import system_prompt
+from tensorrt_llm.scaffolding.controller import Controller
+from tensorrt_llm.scaffolding.task import ChatTask, MCPCallTask, SystemMessage, Task, UserMessage
+
+_TAVILY_COMPRESS_SYSTEM_PROMPT = system_prompt(
+    """You compress Tavily search output for a downstream research agent.
+
+## Requirements
+- Keep the original answer structure and result ordering.
+- Preserve result numbers, titles, URLs, and useful date/source metadata.
+- Keep core facts, numbers, names, claims, and evidence relevant to the user goal.
+- Remove secondary, repeated, boilerplate, or low-value details.
+- Do not add facts that are not in the Tavily output.
+""",
+    name="tavily_search.tavily_compress_system_prompt",
+)
+
+_TAVILY_COMPRESS_USER_PROMPT = """## User Goal
+{goal}
+
+## Tavily Search Output
+{search_output}
+"""
+
+_DEFAULT_COMPRESS_THRESHOLD_CHARS = 6000
+_DEFAULT_MAX_INPUT_CHARS = 24000
+_DEFAULT_MAX_COMPRESSED_CHARS = 6000
+_DEFAULT_MAX_OUTPUT_TOKENS = 2048
+
+LOGGER = logging.getLogger(__name__)
+
+
+def _truncate_with_notice(content: str, max_chars: int, source: str) -> str:
+    if len(content) <= max_chars:
+        return content
+    truncated = content[:max_chars].rstrip()
+    return (
+        f"{truncated}\n\n"
+        f"[truncated {source}: kept first {max_chars} characters to control prompt size]"
+    )
+
+
+def _last_assistant_content(chat_task: ChatTask) -> Optional[str]:
+    for message in reversed(chat_task.messages):
+        if getattr(message, "role", None) == "assistant":
+            return message.content or ""
+    return None
+
+
+@dataclass
+class TavilyTask(Task):
+    """Queries and goal for Tavily search plus optional LLM compression."""
+
+    query: Optional[List[str]] = field(default=None)
+    goal: Optional[str] = field(default=None)
+    result_str: Optional[str] = field(default=None)
+    result_stdout: Optional[str] = field(default=None)
+    result_stderr: Optional[str] = field(default=None)
+
+
+class TavilyController(Controller):
+    """MCP ``tavily_search``, then compress oversized search output."""
+
+    class WorkerTag(Enum):
+        TOOL_CALL = "tavily_tool_call"
+
+    def __init__(
+        self,
+        generation_controller: Controller,
+        compress_threshold_chars: int = _DEFAULT_COMPRESS_THRESHOLD_CHARS,
+        max_input_chars: int = _DEFAULT_MAX_INPUT_CHARS,
+        max_compressed_chars: int = _DEFAULT_MAX_COMPRESSED_CHARS,
+        max_output_tokens: int = _DEFAULT_MAX_OUTPUT_TOKENS,
+    ):
+        super().__init__()
+        self.generation_controller = generation_controller
+        self.compress_threshold_chars = compress_threshold_chars
+        self.max_input_chars = max_input_chars
+        self.max_compressed_chars = max_compressed_chars
+        self.max_output_tokens = max_output_tokens
+
+    def clone(self):
+        return TavilyController(
+            generation_controller=self.generation_controller.clone(),
+            compress_threshold_chars=self.compress_threshold_chars,
+            max_input_chars=self.max_input_chars,
+            max_compressed_chars=self.max_compressed_chars,
+            max_output_tokens=self.max_output_tokens,
+        )
+
+    def process(self, tasks: List[Task], **kwargs):
+        assert len(tasks) == 1 and isinstance(tasks[0], TavilyTask), (
+            "TavilyController only supports a single TavilyTask"
+        )
+        tavily_task = tasks[0]
+        LOGGER.warning(
+            "[tavily] search start: query_count=%d compress_threshold_chars=%d",
+            len(tavily_task.query or []),
+            self.compress_threshold_chars,
+        )
+
+        mcp_task = MCPCallTask.create_mcptask(
+            tool_call_id="tavily_search",
+            tool_name="tavily_search",
+            args=json.dumps({"query": tavily_task.query or []}),
+            worker_tag=self.WorkerTag.TOOL_CALL,
+        )
+        yield [mcp_task]
+
+        raw_result = mcp_task.result_str or ""
+        tavily_task.result_stdout = mcp_task.result_stdout
+        tavily_task.result_stderr = mcp_task.result_stderr
+        if len(raw_result) <= self.compress_threshold_chars:
+            tavily_task.result_str = raw_result
+            return
+
+        LOGGER.warning("[tavily] compressing search output: raw_chars=%d", len(raw_result))
+        bounded_result = _truncate_with_notice(raw_result, self.max_input_chars, "Tavily output")
+        user_prompt = _TAVILY_COMPRESS_USER_PROMPT.format(
+            goal=tavily_task.goal or "Extract relevant information for the research task.",
+            search_output=bounded_result,
+        )
+        chat_task = ChatTask.create_from_messages(
+            [
+                SystemMessage(content=_TAVILY_COMPRESS_SYSTEM_PROMPT),
+                UserMessage(user_prompt),
+            ]
+        )
+        chat_task.max_tokens = self.max_output_tokens
+        chat_task.temperature = 0.0
+
+        yield from self.generation_controller.process([chat_task])
+
+        compressed = _last_assistant_content(chat_task)
+        if compressed is None:
+            tavily_task.result_str = raw_result
+            return
+
+        tavily_task.result_str = _truncate_with_notice(
+            compressed.strip(),
+            self.max_compressed_chars,
+            "compressed Tavily output",
+        )
diff --git a/examples/scaffolding/mcp/tavily_search/tavily_search.py b/examples/scaffolding/mcp/tavily_search/tavily_search.py
new file mode 100644
index 000000000000..70821be3e767
--- /dev/null
+++ b/examples/scaffolding/mcp/tavily_search/tavily_search.py
@@ -0,0 +1,202 @@
+"""MCP server: web search via Tavily API."""
+
+import asyncio
+import logging
+import os
+from pathlib import Path
+
+import httpx
+import uvicorn
+import yaml
+from mcp.server import Server
+from mcp.server.fastmcp import FastMCP
+from mcp.server.sse import SseServerTransport
+from starlette.applications import Starlette
+from starlette.requests import Request
+from starlette.responses import Response
+from starlette.routing import Mount, Route
+
+logging.basicConfig(level=logging.INFO)
+LOGGER = logging.getLogger(__name__)
+
+mcp = FastMCP("tavily_search")
+
+
+def _resolve_config_path(config_path: str) -> Path | None:
+    """Resolve ``--config`` to an existing file.
+
+    ``uv run --directory <mcp_dir>`` sets *cwd* to that directory, so a path
+    relative to the repo root (e.g. ``examples/scaffolding/contrib/...``) does
+    not resolve from cwd. Try cwd first, then each ancestor of this file.
+    """
+    raw = Path(config_path).expanduser()
+    if raw.is_file():
+        return raw.resolve()
+    if raw.is_absolute():
+        return None
+    rel = Path(config_path)
+    here = Path(__file__).resolve().parent
+    seen: set[Path] = set()
+    for base in (Path.cwd(), here, *here.parents):
+        base = base.resolve()
+        if base in seen:
+            continue
+        seen.add(base)
+        cand = (base / rel).resolve()
+        if cand.is_file():
+            return cand
+    return None
+
+
+def _mcp_bind_from_cfg(cfg: dict, service: str, default_port: int) -> tuple[str, int]:
+    svc = (cfg.get("mcp_tools") or {}).get(service) or {}
+    return str(svc.get("host", "0.0.0.0")), int(svc.get("port", default_port))
+
+
+def _load_config(config_path: str | None = None) -> dict:
+    cfg = {}
+    if config_path:
+        resolved = _resolve_config_path(config_path)
+        if resolved is None:
+            LOGGER.warning(
+                "Config file not found: %s (cwd=%s). API keys fall back to environment variables.",
+                config_path,
+                Path.cwd(),
+            )
+        else:
+            with open(resolved) as f:
+                cfg = yaml.safe_load(f) or {}
+            LOGGER.info("Loaded config from %s", resolved)
+
+    def _get(yaml_key: str, env_key: str, default: str = "") -> str:
+        return str(cfg.get(yaml_key, "") or os.getenv(env_key, default))
+
+    mcp_host, mcp_port = _mcp_bind_from_cfg(cfg, "tavily_search", 8087)
+    return {
+        "search_api_key": _get("tavily_api_key", "TAVILY_API_KEY"),
+        "search_api_url": _get("tavily_api_url", "TAVILY_API_URL", "https://api.tavily.com/search"),
+        "mcp_host": mcp_host,
+        "mcp_port": mcp_port,
+    }
+
+
+_CFG: dict = {
+    "search_api_key": os.getenv("TAVILY_API_KEY", ""),
+    "search_api_url": os.getenv("TAVILY_API_URL", "https://api.tavily.com/search"),
+}
+
+
+async def _search_single(client: httpx.AsyncClient, query: str) -> str:
+    payload = {
+        "api_key": _CFG["search_api_key"],
+        "query": query,
+        "max_results": 10,
+    }
+
+    for attempt in range(3):
+        try:
+            resp = await client.post(
+                _CFG["search_api_url"],
+                json=payload,
+                timeout=30,
+            )
+            resp.raise_for_status()
+            results = resp.json()
+            organic = results.get("results", [])
+            if not organic:
+                if attempt < 2:
+                    await asyncio.sleep(1)
+                    continue
+                return f"No results found for '{query}'."
+            snippets = []
+            for idx, page in enumerate(organic, 1):
+                title = page.get("title", "No title")
+                link = page.get("url", "")
+                snippet = page.get("content", "")
+                date = page.get("published_date", "")
+                source = page.get("source", "")
+                date_str = f"\nDate published: {date}" if date else ""
+                source_str = f"\nSource: {source}" if source else ""
+                snippet_str = f"\n{snippet}" if snippet else ""
+                snippets.append(f"{idx}. [{title}]({link}){date_str}{source_str}{snippet_str}")
+            return (
+                f"A Tavily search for '{query}' found "
+                f"{len(snippets)} results:\n\n## Web Results\n" + "\n\n".join(snippets)
+            )
+        except Exception as e:
+            if attempt == 2:
+                return f"Search failed for '{query}': {e}"
+            await asyncio.sleep(2)
+    return f"No results found for '{query}'."
+
+
+@mcp.tool()
+async def tavily_search(query: list[str]) -> str:
+    """Web search via Tavily API. Returns formatted results for each query."""
+    if not _CFG["search_api_key"]:
+        return "[tavily_search] Error: search_api_key not configured."
+    async with httpx.AsyncClient() as client:
+        tasks = [_search_single(client, q) for q in query]
+        results = await asyncio.gather(*tasks)
+    return "\n=======\n".join(results)
+
+
+def create_starlette_app(mcp_server: Server, *, debug: bool = False) -> Starlette:
+    sse = SseServerTransport("/messages/")
+
+    async def handle_sse(request: Request) -> Response:
+        async with sse.connect_sse(
+            request.scope,
+            request.receive,
+            request._send,  # noqa: SLF001
+        ) as (read_stream, write_stream):
+            await mcp_server.run(
+                read_stream,
+                write_stream,
+                mcp_server.create_initialization_options(),
+            )
+        return Response()
+
+    return Starlette(
+        debug=debug,
+        routes=[
+            Route("/sse", endpoint=handle_sse),
+            Mount("/messages/", app=sse.handle_post_message),
+        ],
+    )
+
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Tavily Search MCP SSE-based server")
+    parser.add_argument(
+        "--config", type=str, default=None, help="Path to config.yaml (API keys, endpoints)"
+    )
+    parser.add_argument("--host", default=None, help="Host to bind to (overrides config)")
+    parser.add_argument(
+        "--port", type=int, default=None, help="Port to listen on (overrides config)"
+    )
+    args = parser.parse_args()
+
+    _CFG.update(_load_config(args.config))
+
+    _has_search_key = bool(str(_CFG.get("search_api_key", "")).strip())
+    _key_status = "detected" if _has_search_key else "not detected (empty or missing)"
+    if _has_search_key:
+        LOGGER.info(
+            "Tavily API key (TAVILY_API_KEY / config tavily_api_key): %s",
+            _key_status,
+        )
+    else:
+        LOGGER.warning(
+            "Tavily API key (TAVILY_API_KEY / config tavily_api_key): %s",
+            _key_status,
+        )
+
+    host = args.host or _CFG.get("mcp_host", "0.0.0.0")
+    port = args.port or _CFG.get("mcp_port", 8087)
+
+    mcp_server = mcp._mcp_server  # noqa: WPS437
+    starlette_app = create_starlette_app(mcp_server, debug=True)
+    uvicorn.run(starlette_app, host=host, port=port)
diff --git a/examples/scaffolding/contrib/mcp/weather/pyproject.toml b/examples/scaffolding/mcp/weather/pyproject.toml
similarity index 100%
rename from examples/scaffolding/contrib/mcp/weather/pyproject.toml
rename to examples/scaffolding/mcp/weather/pyproject.toml
diff --git a/examples/scaffolding/contrib/mcp/weather/weather.py b/examples/scaffolding/mcp/weather/weather.py
similarity index 78%
rename from examples/scaffolding/contrib/mcp/weather/weather.py
rename to examples/scaffolding/mcp/weather/weather.py
index fb542bbc008f..e98f843c44da 100644
--- a/examples/scaffolding/contrib/mcp/weather/weather.py
+++ b/examples/scaffolding/mcp/weather/weather.py
@@ -33,11 +33,11 @@ def format_alert(feature: dict) -> str:
     """Format an alert feature into a readable string."""
     props = feature["properties"]
     return f"""
-Event: {props.get('event', 'Unknown')}
-Area: {props.get('areaDesc', 'Unknown')}
-Severity: {props.get('severity', 'Unknown')}
-Description: {props.get('description', 'No description available')}
-Instructions: {props.get('instruction', 'No specific instructions provided')}
+Event: {props.get("event", "Unknown")}
+Area: {props.get("areaDesc", "Unknown")}
+Severity: {props.get("severity", "Unknown")}
+Description: {props.get("description", "No description available")}
+Instructions: {props.get("instruction", "No specific instructions provided")}
 """
 
 
@@ -88,27 +88,25 @@ async def get_forecast(latitude: float, longitude: float) -> str:
     forecasts = []
     for period in periods[:5]:  # Only show next 5 periods
         forecast = f"""
-{period['name']}:
-Temperature: {period['temperature']}°{period['temperatureUnit']}
-Wind: {period['windSpeed']} {period['windDirection']}
-Forecast: {period['detailedForecast']}
+{period["name"]}:
+Temperature: {period["temperature"]}°{period["temperatureUnit"]}
+Wind: {period["windSpeed"]} {period["windDirection"]}
+Forecast: {period["detailedForecast"]}
 """
         forecasts.append(forecast)
 
     return "\n---\n".join(forecasts)
 
 
-def create_starlette_app(mcp_server: Server,
-                         *,
-                         debug: bool = False) -> Starlette:
+def create_starlette_app(mcp_server: Server, *, debug: bool = False) -> Starlette:
     """Create a Starlette application that can server the provided mcp server with SSE."""
     sse = SseServerTransport("/messages/")
 
     async def handle_sse(request: Request) -> None:
         async with sse.connect_sse(
-                request.scope,
-                request.receive,
-                request._send,  # noqa: SLF001
+            request.scope,
+            request.receive,
+            request._send,  # noqa: SLF001
         ) as (read_stream, write_stream):
             await mcp_server.run(
                 read_stream,
@@ -130,12 +128,9 @@ async def handle_sse(request: Request) -> None:
 
     import argparse
 
-    parser = argparse.ArgumentParser(description='Run MCP SSE-based server')
-    parser.add_argument('--host', default='0.0.0.0', help='Host to bind to')
-    parser.add_argument('--port',
-                        type=int,
-                        default=8080,
-                        help='Port to listen on')
+    parser = argparse.ArgumentParser(description="Run MCP SSE-based server")
+    parser.add_argument("--host", default="0.0.0.0", help="Host to bind to")
+    parser.add_argument("--port", type=int, default=8080, help="Port to listen on")
     args = parser.parse_args()
 
     # Bind SSE request handling to MCP server
diff --git a/examples/scaffolding/contrib/open_deep_research/WordLlama/README.md b/examples/scaffolding/mcp/wordllama/README.md
similarity index 100%
rename from examples/scaffolding/contrib/open_deep_research/WordLlama/README.md
rename to examples/scaffolding/mcp/wordllama/README.md
diff --git a/examples/scaffolding/contrib/open_deep_research/WordLlama/main.py b/examples/scaffolding/mcp/wordllama/main.py
similarity index 100%
rename from examples/scaffolding/contrib/open_deep_research/WordLlama/main.py
rename to examples/scaffolding/mcp/wordllama/main.py
diff --git a/examples/scaffolding/contrib/open_deep_research/WordLlama/pyproject.toml b/examples/scaffolding/mcp/wordllama/pyproject.toml
similarity index 100%
rename from examples/scaffolding/contrib/open_deep_research/WordLlama/pyproject.toml
rename to examples/scaffolding/mcp/wordllama/pyproject.toml
diff --git a/examples/scaffolding/contrib/open_deep_research/WordLlama/wordllama_serve.py b/examples/scaffolding/mcp/wordllama/wordllama_serve.py
similarity index 100%
rename from examples/scaffolding/contrib/open_deep_research/WordLlama/wordllama_serve.py
rename to examples/scaffolding/mcp/wordllama/wordllama_serve.py
diff --git a/examples/scaffolding/trace_replay/README.md b/examples/scaffolding/trace_replay/README.md
new file mode 100644
index 000000000000..f3fbe5c8bd3f
--- /dev/null
+++ b/examples/scaffolding/trace_replay/README.md
@@ -0,0 +1,360 @@
+# Trace Replay via Scaffolding
+
+A practical write-up of the `trace & replay` workflow in TensorRT-LLM
+scaffolding. Read it once and walk away with a mental model of the full
+pipeline.
+
+## Why Trace Replay Exists
+
+Scaffolding agents such as Coder, IterResearch, and Open Deep Research are
+not single-shot generations. A typical run includes:
+
+- multi-turn conversation state,
+- MCP tool calls,
+- parallel branches,
+- and token-heavy context evolution over time.
+
+When performance shifts, the final answer alone does not tell you enough.
+You usually need to know:
+
+- What exact execution structure did this request follow?
+- How much of wall time came from model generation vs tool waiting?
+- How do throughput and latency change across serving setups?
+
+Trace replay addresses this by converting one real agent execution into a
+structured event stream, then replaying the same structure against another
+endpoint/model configuration with comparable metrics.
+
+## Directory Layout
+
+```
+examples/scaffolding/trace_replay/
+├── README.md                  -- this file
+├── run_trace_replay.py        -- single-trace single-config replay driver
+├── metrics.py                 -- replay-result metrics (used by run_trace_replay)
+├── trace_example/             -- one ready-to-run example trace
+│   └── matplotlib__matplotlib-23412/
+│       └── matplotlib__matplotlib-23412.trace.json   (compact)
+└── analysis/                  -- offline KV-cache hit-rate upper-bound analyzer
+    ├── compute_cache_hit_trace.py   CLI: optimal upper-bound hit rate per trace
+    ├── cache_hit.py / aggregation.py / annotate.py / blocks.py /
+    │   branch_summary.py / streams.py / io.py / __init__.py
+    └── README.md
+```
+
+Two workflows are covered:
+
+| Goal | Entry point |
+|---|---|
+| Replay one trace once against one serving config | `run_trace_replay.py` |
+| Offline upper bound on KV-cache hit rate (no GPU) | `analysis/compute_cache_hit_trace.py` |
+
+## The Core Design in One Picture
+
+The implementation follows a four-stage pipeline:
+
+1. **Trace capture** during controller execution (`ExecutionTracer`).
+2. **Trace artifact export** as compact and full JSON files.
+3. **Replay execution** with `ReplayEngine` and `TRTOpenaiWorker`.
+4. **Metrics aggregation** into a single JSON report.
+
+Key design choices:
+
+- **Structure-first reproducibility**: preserve event order, branch
+  topology, and token budgets.
+- **Tool replay decoupling**: replay tool calls as timed waits
+  (`duration_ms`) instead of re-executing external tools.
+- **Parallel semantics preserved**: branch routing via `branch_path` plus
+  `parallel_start`/`parallel_end`.
+- **Two trace flavors**: compact for replay/benchmarking, full for
+  debugging and forensic analysis.
+
+## Trace: Data Model and Capture Mechanics
+
+### The trace schema
+
+The canonical schema lives in `tensorrt_llm/scaffolding/execution_trace.py`:
+
+- `TraceEvent`
+- `ExecutionTrace`
+
+Important event types:
+
+- `message`
+- `tool_call`
+- `parallel_start`
+- `parallel_end`
+- `drop_kv_cache`
+
+Critical fields:
+
+- `branch_path` identifies the parallel branch.
+- `conversation_id` and `message_index` preserve conversation ordering.
+- assistant message events carry `prompt_tokens`, `completion_tokens`,
+  `reasoning_tokens`, and `finish_reason`.
+
+### Where tracing is attached
+
+Tracing is wired in controller factories through decorators:
+
+- `with_execution_tracing(...)` to attach `ExecutionTracer`
+- `tokenize_trace_scope()` to fill token counts for tokenizable
+  non-assistant messages (used in some scaffolds)
+- `scaffolding_llm.enable_output_task_collection()` to return tracer
+  output via results
+
+Representative integration points:
+
+- `tensorrt_llm/scaffolding/contrib/iter_research/agent.py`
+- `tensorrt_llm/scaffolding/contrib/open_deep_research/supervisor.py`
+- `tensorrt_llm/scaffolding/contrib/Coder/coder.py`
+
+### How `ExecutionTracer` records events
+
+The core implementation is in `tensorrt_llm/scaffolding/task_collection.py`
+(`ExecutionTracer`).
+
+It works in phases:
+
+- **`before_yield`**: records pre-existing context messages
+  (system/user/tool) for each `ChatTask`.
+- **`after_yield`**: records produced assistant events plus generation
+  metadata (tokens, duration, tool calls).
+- **parallel handling**: emits `parallel_start`/`parallel_end` and rewrites
+  child event paths onto sub-branches.
+
+Token accounting support:
+
+- `tokenize_trace_scope()` creates `TokenizeTask` items and uses the
+  generation worker's `/tokenize` endpoint.
+- `_correct_system_tokens(...)` then adjusts first system-token counts
+  using assistant prompt-token evidence (to account for system-side
+  injected context such as tool definitions).
+
+### Compact vs full trace files
+
+`ExecutionTrace.save(path, full=False)` exports:
+
+- **compact trace** (`*.trace.json`): replay-focused structure + token
+  metadata, excluding verbose payload.
+- **full trace** (`*.full.trace.json`): includes message content, LLM
+  request snapshots, tool arguments/results, stdio, and turn-level timing.
+
+Load path for replay is `ExecutionTrace.load(...)`.
+
+### Trace export in example runners
+
+The pattern is consistent across example runners:
+
+1. `tracer = result.task_collections.get("execution_tracer")`
+2. `trace = tracer.export_trace()`
+3. export both compact and full files
+
+You can see this in:
+
+- `examples/scaffolding/contrib/Coder/run_coder.py`
+- `examples/scaffolding/contrib/iter_research/run_iter_research.py`
+- `examples/scaffolding/contrib/open_deep_research/run_open_deep_research.py`
+
+## Replay: What Gets Reconstructed and How
+
+### Replay entrypoints
+
+- `run_trace_replay.py`: one trace, one config, one report — the simplest
+  thing that works. Use this to sanity-check a trace, or to compare two
+  serving configs on a fixed workload.
+
+Built on `ReplayEngine` + `TRTOpenaiWorker`.
+
+Flow for `run_trace_replay.py`:
+
+1. parse CLI args,
+2. load compact trace via `ExecutionTrace.load(...)`,
+3. build `openai.AsyncOpenAI` + `TRTOpenaiWorker`,
+4. replay with `ReplayEngine(...).launch_trace(...)`,
+5. compute and write metrics report.
+
+### Queue-based branch routing
+
+Replay core is in `tensorrt_llm/scaffolding/replay.py`:
+
+- `ReplayEngine`
+- `QueueManager`
+- `QueueExecutor`
+
+Design pattern:
+
+- one queue/executor per branch path,
+- `parallel_start` allocates child queues for `parent_path + (i,)` after
+  draining the parent queue (so the fork happens after the parent's
+  fork-producing generation is fully committed, not while it is still in
+  flight),
+- `parallel_end` closes/waits/cleans child queues,
+- non-parallel events are routed by their `branch_path`.
+
+This preserves:
+
+- strict in-branch ordering,
+- and branch-level concurrency semantics.
+
+### Event replay semantics
+
+`QueueExecutor` handles each event category differently:
+
+- **`tool_call`**: simulated via `asyncio.sleep(duration_ms / 1000)` (no
+  real external tool call).
+- **`message` with role `system`/`user`/`tool`**: synthetic token IDs
+  generated from recorded token counts and appended to conversation
+  context. System messages are cached by `event.system_prompt_id` (or
+  `conv:<conv_id>` for untagged templates) so multiple conversations using
+  the same template share a token-id prefix — mirroring a real prefix
+  cache hit.
+- **`message` with role `assistant`**:
+  - build `GenerationTask.input_tokens` from accumulated conversation
+    segments,
+  - set `max_tokens` to recorded `completion_tokens`,
+  - run real generation through worker,
+  - strip leading reasoning tokens (`reasoning_tokens`) before writing
+    content tokens back into context,
+  - record per-call client-side wall-clock start/end for downstream
+    steady-state-window analytics.
+
+### Worker behavior during replay
+
+The default replay worker is `TRTOpenaiWorker` in
+`tensorrt_llm/scaffolding/worker.py`.
+
+In replay, assistant generation is driven by `GenerationTask` through
+OpenAI-compatible APIs, with `ignore_eos=True`, using trace-derived token
+budgets as the envelope for generation.
+
+## Metrics: What You Get After Replay
+
+### Single-trace report (`metrics.py`)
+
+`run_trace_replay.py` writes the simple report. Output includes:
+
+- trace structure summaries (event/role/tool counts),
+- tool-time totals from trace metadata,
+- run-level timing and duration stats,
+- throughput metrics (`output_tps_aggregate`, `output_tps_per_gpu`,
+  per-user TPS),
+- assistant-level token details (trace completion budget vs replay output
+  lengths).
+
+Output JSON also includes run schema, timestamps, host/runtime metadata,
+CLI argv, replay endpoint settings, and trace file metadata.
+
+### KV-cache hit-rate analysis (`analysis/`)
+
+`compute_cache_hit_trace.py` is a pure offline simulator: it assumes an
+infinite, non-evicting cache and walks the trace in `QueueExecutor` order,
+scoring each assistant prompt against a token-level radix tree of
+synthetic IDs. Output:
+
+- `<name>.cachehit.json` (summary + per-request stats + rollups by branch /
+  depth / system-prompt UUID) with all hit-rate fields prefixed
+  ``optimal_`` so the offline upper-bound nature is unambiguous
+  (`optimal_overall_cache_block_hit_rate`,
+  `optimal_cache_block_hit_rate` per request, …).
+- `<name>.trace.cachehit.json` (annotated trace with the same `optimal_*`
+  fields stitched onto each scored assistant event).
+
+Defaults mirror real TRT-LLM behavior (`tokens_per_block=32`,
+`--decode-kv-reuse`, `--cot-pollutes-cache`). See `analysis/README.md`
+for the full flag/schema reference.
+
+## Usage: End-to-End Workflow
+
+### 1) Generate traces from a scaffold run
+
+Run a scaffold with `--enable_tracing`; it emits both compact and full
+traces.
+
+```bash
+python examples/scaffolding/contrib/iter_research/run_iter_research.py \
+  --config examples/scaffolding/contrib/open_deep_research/config.example.yaml \
+  --enable_tracing
+```
+
+```bash
+python examples/scaffolding/contrib/open_deep_research/run_open_deep_research.py \
+  --config examples/scaffolding/contrib/open_deep_research/config.example.yaml \
+  --enable_tracing
+```
+
+```bash
+python examples/scaffolding/contrib/Coder/run_coder.py \
+    --base_url http://localhost:8000/v1 \
+    --model Qwen3/Qwen3-30B-A3B \
+    --apiary_url http://172.17.0.1:8080 \
+    --mcp_url http://127.0.0.1:8083/sse \
+    --image ubuntu:22.04 \
+    --prompt "Implement a thread-safe LRU cache in Python" \
+    --max_iterations 50 \
+    --enable_tracing
+```
+
+### 2) Replay the compact trace (single-config)
+
+```bash
+python examples/scaffolding/trace_replay/run_trace_replay.py \
+  examples/scaffolding/trace_replay/trace_example/matplotlib__matplotlib-23412/matplotlib__matplotlib-23412.trace.json \
+  --model "Qwen3-30B-A3B" \
+  --openai-base-url "http://127.0.0.1:8000/v1"
+```
+
+You can replay your own generated traces the same way:
+
+```bash
+python examples/scaffolding/trace_replay/run_trace_replay.py \
+  iter_research_trace_20260422_125644/iter_research.trace.json \
+  --model "Qwen3-30B-A3B" \
+  --openai-base-url "http://127.0.0.1:8000/v1"
+```
+
+Useful options:
+
+- `--openai-api-key` (or `OPENAI_API_KEY`)
+- `--tensor-parallel-size` (used for per-GPU normalization)
+- `--output-json` (custom report path)
+
+Default output filename:
+
+- `<trace_base>_<model>_replay_statistics_<YYYYMMDD_HHMMSS>.json`
+
+### 3) Compute KV-cache hit rates
+
+Offline ideal upper bound from a trace (no GPU needed):
+
+```bash
+# Single trace dir
+python examples/scaffolding/trace_replay/analysis/compute_cache_hit_trace.py \
+  path/to/<task>/
+
+# Whole dataset
+python examples/scaffolding/trace_replay/analysis/compute_cache_hit_trace.py \
+  path/to/dataset/
+
+# Single trace file
+python examples/scaffolding/trace_replay/analysis/compute_cache_hit_trace.py \
+  path/to/some.trace.json
+```
+
+See `analysis/README.md` for flags and output schema.
+
+## Practical Boundaries and Gotchas
+
+- Replay is **structure-faithful**, not text-faithful; generated wording
+  may differ from original trace output.
+- Tool calls are not re-run; they are timing-simulated from historical
+  `duration_ms`.
+- Assistant replay requires `completion_tokens > 0`; otherwise replay
+  will fail for that turn.
+- Parallel trace topology must be valid (properly paired `parallel_start`
+  / `parallel_end`).
+- Full traces can be very large; use compact traces for routine replay
+  benchmarking.
+- `optimal_cache_hit` from `analysis/` is an offline upper bound on
+  block-reuse; the engine-measured rate at runtime will be lower due to
+  scheduling and eviction losses, not a bug.
diff --git a/examples/scaffolding/trace_replay/analysis/README.md b/examples/scaffolding/trace_replay/analysis/README.md
new file mode 100644
index 000000000000..f60038a689a3
--- /dev/null
+++ b/examples/scaffolding/trace_replay/analysis/README.md
@@ -0,0 +1,109 @@
+# Trace KV-Cache Hit-Rate Analysis
+
+Offline simulator that takes a scaffolding `*.trace.json` and produces a
+per-request and aggregate prefix KV-cache hit-rate report. Assumes an
+**infinite, non-evicting** cache, so the result is an upper bound on what
+a real TRT-LLM deployment with the same block size could achieve — useful
+for comparing routing / branching strategies without standing up a server.
+
+## Quick start
+
+```bash
+# Single trace dir
+python compute_cache_hit_trace.py path/to/<task>/
+
+# Whole dataset (each subdir is one trace)
+python compute_cache_hit_trace.py path/to/dataset/
+
+# A single trace file
+python compute_cache_hit_trace.py path/to/1.trace.json
+```
+
+Outputs land next to each input:
+
+| File | What it is |
+|------|------------|
+| `<name>.cachehit.json` | Full record: per-request stats + aggregate `summary` + optional rollups. |
+| `<name>.trace.cachehit.json` | Deep copy of the original trace with `optimal_cache_hit_rate`, `optimal_cache_hit_tokens`, `optimal_cache_miss_tokens`, `optimal_cache_block_hit_rate` attached to each scored assistant event. |
+| `<dataset>.cachehit.json` | Dataset-level aggregate (only when input is a dataset). |
+
+## Key flags
+
+All flags use `argparse.BooleanOptionalAction`, so `--flag` enables and
+`--no-flag` disables; defaults are shown below.
+
+| Flag | Default | Meaning |
+|------|---------|---------|
+| `--tokens-per-block N` | `32` | KV block size. Match your runtime config. |
+| `--decode-kv-reuse` / `--no-decode-kv-reuse` | **on** | Insert assistant decode tokens into the cache so later turns in the same conversation can hit them. Disable to model "decode KV is dropped at request end". |
+| `--cot-pollutes-cache` / `--no-cot-pollutes-cache` | **on** | When on, store `[prompt + reasoning + content]` in the radix tree — mirrors real TRT-LLM C++ KV manager. Subsequent prompts omit prior reasoning and diverge at the reasoning-insertion block. Off = optimistic upper bound where reasoning is treated as if it never occupied KV. Only meaningful when `--decode-kv-reuse` is on. |
+| `--no-rollups` | off | Skip per-(branch root / depth / system-prompt UUID) rollups. |
+
+**Default behavior** (no flags) = the most realistic model:
+`decode_kv_reuse=True`, `cot_pollutes_cache=True`, `tokens_per_block=32`.
+
+## How it works (one screen)
+
+1. **Pre-warm.** Sweep the trace once to find every distinct `system_prompt_id` UUID. Allocate a synthetic token stream per UUID (longest length seen) and insert its full blocks into the radix tree. Every cross-conversation reuse of the same system prompt is then a guaranteed hit.
+
+2. **Walk events in order**, mirroring `tensorrt_llm.scaffolding.trace_replay.replay.QueueExecutor`:
+
+   - **system** → segment built from the UUID-shared token stream.
+   - **user / tool** → segment built from fresh allocator tokens (no cross-conversation collisions).
+   - **assistant** → assemble the prompt by concatenating segments, score it against the radix tree (only complete matching blocks count as hits), then optionally insert the decode-time KV stream back into the cache.
+
+3. **Decode-time insertion.** What goes into the radix tree after each assistant event depends on the two flags above:
+
+   | `decode_kv_reuse` | `cot_pollutes_cache` | Inserted sequence |
+   |---|---|---|
+   | False | — | nothing |
+   | True | False | `[prompt + content]` — optimistic upper bound |
+   | True | True (default) | `[prompt + reasoning + content]` — real C++ behavior |
+
+   In all cases the *conversation segment store* only ever records `content = completion - reasoning`, so next-turn prompt assembly skips reasoning. The difference between the two `True/False` modes is whether reasoning blocks **also live in the cache** — when they do, a later turn's prompt diverges from the cached prefix at the reasoning-insertion block and all subsequent blocks miss.
+
+4. **Aggregate.** Sum per-request stats into `summary`. Optionally emit per-(branch root / branch depth / system-prompt UUID) rollups for branched workflows (ToT, Open Deep Research).
+
+All branches in a trace share a single global cache (most permissive UB).
+
+## Output schema (most useful fields)
+
+`summary` block:
+
+| Field | Meaning |
+|------|---------|
+| `llm_request_count` | Assistant events scored. |
+| `total_prompt_tokens` | Sum of `prompt_tokens` across requests. |
+| `optimal_total_cache_hit_tokens` / `optimal_total_cache_miss_tokens` | Hit / miss accounting in tokens, offline UB. |
+| `optimal_overall_cache_hit_rate` | `optimal_total_cache_hit_tokens / total_prompt_tokens`. |
+| `optimal_overall_cache_block_hit_rate` | Block-granular UB rate. |
+| `minimal_cache_blocks` / `minimal_cache_tokens` | Total distinct blocks in the radix tree at end of trace. Grows when `cot_pollutes_cache=True` (reasoning blocks get stored). |
+| `preloaded_system_blocks` | Blocks pre-inserted in phase 1. |
+
+Each entry of `requests[]` carries the same hit-rate fields plus `reasoning_tokens`, `reusable_completion_tokens`, `branch_path`, `system_prompt_id_seed`.
+
+The `algorithm` block surfaces the flags that produced the run
+(`tokens_per_block`, `decode_kv_reuse`, `cot_pollutes_cache`, …) so
+different runs are self-describing.
+
+## File map
+
+| File | Role |
+|------|------|
+| `compute_cache_hit_trace.py` | CLI entry point. Thin wrapper around the package. |
+| `cache_hit.py` | Core: `compute_cache_hit_upper_bound`, the two-phase scoring loop. |
+| `streams.py` | `TokenIdAllocator`, `SystemPromptRegistry`, `ConversationSegments` — synthetic token streams and per-(branch, conversation) segment store. |
+| `blocks.py` | `TokenPrefixCache` (token-level radix tree) + engine-aligned block-count helpers. |
+| `branch_summary.py` | Per-branch / per-depth / per-system-prompt rollups. |
+| `aggregation.py` | Dataset-level aggregate across many traces. |
+| `annotate.py` | Builds the `*.trace.cachehit.json` annotated trace. |
+| `io.py` | Input resolution + JSON file I/O. |
+| `__init__.py` | Public API surface (`compute_cache_hit_upper_bound`, etc.). |
+
+## Limitations
+
+- **Infinite cache, no eviction.** Real deployments evict under capacity pressure; that downward correction is not modeled here.
+- **Structure-only.** Synthetic token IDs are deterministic but arbitrary. The simulator captures prefix-tree topology, not real tokenization or kernel-level effects.
+- **Strict mode.** Every `role=system` event must carry a `system_prompt_id` UUID (older traces without it will be rejected). `drop_kv_cache` events are also rejected — those imply a non-infinite cache.
+
+For deeper internals (parent-branch inheritance, boundary-block semantics, full schema enumeration, worked examples) see `cache_hit.py` and `streams.py` docstrings.
diff --git a/examples/scaffolding/trace_replay/analysis/__init__.py b/examples/scaffolding/trace_replay/analysis/__init__.py
new file mode 100644
index 000000000000..e6a8eb8d3702
--- /dev/null
+++ b/examples/scaffolding/trace_replay/analysis/__init__.py
@@ -0,0 +1,60 @@
+r"""KV-cache hit-rate analysis for scaffolding traces.
+
+Public entry point: :func:`compute_cache_hit_upper_bound` — give it a parsed
+trace and it returns a JSON-serializable hit-rate record under the
+infinite-capacity prefix-cache assumption, with all distinct
+``system_prompt_id`` templates pre-loaded into the radix tree before any
+request is scored. Branched / parallel sub-agent traces (Tree of Thought,
+Open Deep Research) are supported under the shared global-cache policy and
+emit per-(branch root / branch depth / system prompt) rollups.
+"""
+
+from .aggregation import DATASET_SCHEMA, aggregate_dataset_record
+from .annotate import ANNOTATION_FIELDS, build_annotated_trace
+from .blocks import (
+    TokenPrefixCache,
+    engine_aligned_block_count,
+    engine_aligned_hit_blocks,
+    validate_tokens_per_block,
+)
+from .branch_summary import compute_branch_rollups, merge_rollup_arrays
+from .cache_hit import SCHEMA, compute_cache_hit_upper_bound
+from .io import (
+    ANNOTATED_TRACE_SUFFIX,
+    OUTPUT_SUFFIX,
+    default_annotated_trace_path,
+    default_dataset_output_path,
+    default_output_path,
+    load_trace,
+    resolve_input_trace_files,
+    resolve_trace_file,
+    write_json,
+)
+from .streams import ConversationSegments, SystemPromptRegistry, TokenIdAllocator
+
+__all__ = [
+    "ANNOTATED_TRACE_SUFFIX",
+    "ANNOTATION_FIELDS",
+    "ConversationSegments",
+    "DATASET_SCHEMA",
+    "OUTPUT_SUFFIX",
+    "SCHEMA",
+    "SystemPromptRegistry",
+    "TokenIdAllocator",
+    "TokenPrefixCache",
+    "aggregate_dataset_record",
+    "build_annotated_trace",
+    "compute_branch_rollups",
+    "compute_cache_hit_upper_bound",
+    "default_annotated_trace_path",
+    "default_dataset_output_path",
+    "default_output_path",
+    "engine_aligned_block_count",
+    "engine_aligned_hit_blocks",
+    "load_trace",
+    "merge_rollup_arrays",
+    "resolve_input_trace_files",
+    "resolve_trace_file",
+    "validate_tokens_per_block",
+    "write_json",
+]
diff --git a/examples/scaffolding/trace_replay/analysis/aggregation.py b/examples/scaffolding/trace_replay/analysis/aggregation.py
new file mode 100644
index 000000000000..8840b16c0628
--- /dev/null
+++ b/examples/scaffolding/trace_replay/analysis/aggregation.py
@@ -0,0 +1,113 @@
+r"""Dataset-level aggregation of per-trace cache-hit records."""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Sequence
+
+from .branch_summary import merge_rollup_arrays
+
+DATASET_SCHEMA = "scaffolding.cache_hit_dataset.v4"
+
+
+_TRACE_LEVEL_RATE_FIELDS = (
+    ("optimal_overall_cache_hit_rate", "optimal_trace_cache_hit_rate"),
+    ("optimal_overall_cache_block_hit_rate", "optimal_trace_cache_block_hit_rate"),
+)
+
+_SUMMABLE_SUMMARY_FIELDS = (
+    "event_count",
+    "llm_request_count",
+    "total_prompt_tokens",
+    "optimal_total_cache_hit_blocks",
+    "optimal_total_cache_miss_blocks",
+    "optimal_total_cache_hit_tokens",
+    "optimal_total_cache_miss_tokens",
+    "minimal_cache_blocks",
+    "preloaded_system_blocks",
+    "distinct_system_prompts",
+)
+
+_ROLLUP_KINDS = (
+    ("by_branch_root", False),
+    ("by_branch_depth", True),
+    ("by_system_prompt", False),
+)
+
+
+def aggregate_dataset_record(trace_records: Sequence[Dict[str, Any]]) -> Dict[str, Any]:
+    """Combine per-trace records into a flat dataset-level summary record."""
+    sums: Dict[str, int] = {field: 0 for field in _SUMMABLE_SUMMARY_FIELDS}
+    max_prompt_tokens = 0
+    rate_buckets: Dict[str, List[float]] = {
+        out_field: [] for _, out_field in _TRACE_LEVEL_RATE_FIELDS
+    }
+
+    for record in trace_records:
+        summary = record["summary"]
+        for field in _SUMMABLE_SUMMARY_FIELDS:
+            sums[field] += summary.get(field, 0)
+        max_prompt_tokens = max(max_prompt_tokens, summary.get("max_prompt_tokens", 0))
+        for in_field, out_field in _TRACE_LEVEL_RATE_FIELDS:
+            rate_buckets[out_field].append(summary.get(in_field, 0.0))
+
+    optimal_overall_cache_hit_rate = _safe_div(
+        sums["optimal_total_cache_hit_tokens"], sums["total_prompt_tokens"]
+    )
+    optimal_overall_cache_block_hit_rate = _safe_div(
+        sums["optimal_total_cache_hit_blocks"],
+        sums["optimal_total_cache_hit_blocks"] + sums["optimal_total_cache_miss_blocks"],
+    )
+
+    algorithm = dict(trace_records[0]["algorithm"]) if trace_records else {}
+    if algorithm:
+        algorithm["cache_scope"] = "per_trace_independent"
+    tokens_per_block = algorithm.get("tokens_per_block") or 0
+
+    record: Dict[str, Any] = {
+        "schema": DATASET_SCHEMA,
+        "algorithm": algorithm,
+        "trace_count": len(trace_records),
+        **{field: sums[field] for field in _SUMMABLE_SUMMARY_FIELDS},
+        "tokens_per_block": algorithm.get("tokens_per_block"),
+        "decode_kv_reuse": algorithm.get("decode_kv_reuse"),
+        "cot_pollutes_cache": algorithm.get("cot_pollutes_cache"),
+        "preloaded_system_tokens": sums["preloaded_system_blocks"] * tokens_per_block,
+        "minimal_cache_tokens": sums["minimal_cache_blocks"] * tokens_per_block,
+        "optimal_overall_cache_hit_rate": optimal_overall_cache_hit_rate,
+        "optimal_overall_cache_block_hit_rate": optimal_overall_cache_block_hit_rate,
+        "max_prompt_tokens": max_prompt_tokens,
+    }
+
+    for _, out_field in _TRACE_LEVEL_RATE_FIELDS:
+        record.update(_rate_stats(rate_buckets[out_field], out_field))
+
+    rollups: Dict[str, List[Dict[str, Any]]] = {}
+    for kind, sort_numeric in _ROLLUP_KINDS:
+        per_trace = [
+            rec.get("rollups", {}).get(kind, [])
+            for rec in trace_records
+            if rec.get("rollups") is not None
+        ]
+        if per_trace:
+            rollups[kind] = merge_rollup_arrays(per_trace, sort_numeric=sort_numeric)
+    if rollups:
+        record["rollups"] = rollups
+    return record
+
+
+def _rate_stats(values: Sequence[float], field_prefix: str) -> Dict[str, float]:
+    if not values:
+        return {
+            f"mean_{field_prefix}": 0.0,
+            f"min_{field_prefix}": 0.0,
+            f"max_{field_prefix}": 0.0,
+        }
+    return {
+        f"mean_{field_prefix}": sum(values) / len(values),
+        f"min_{field_prefix}": min(values),
+        f"max_{field_prefix}": max(values),
+    }
+
+
+def _safe_div(num: float, denom: float) -> float:
+    return num / denom if denom else 0.0
diff --git a/examples/scaffolding/trace_replay/analysis/annotate.py b/examples/scaffolding/trace_replay/analysis/annotate.py
new file mode 100644
index 000000000000..4dbdf7d19c2e
--- /dev/null
+++ b/examples/scaffolding/trace_replay/analysis/annotate.py
@@ -0,0 +1,56 @@
+r"""Build a trace JSON augmented with per-request offline upper-bound metrics.
+
+The output mirrors the input ``*.trace.json`` schema exactly, except every
+assistant ``message`` event that produced a scored request gets the
+``optimal_*`` upper-bound fields copied from the corresponding request
+record. Downstream tools can then view per-event UB metrics inline without
+joining against the separate ``*.cachehit.json`` summary.
+"""
+
+from __future__ import annotations
+
+import copy
+from typing import Any, Dict
+
+ANNOTATION_FIELDS = (
+    "optimal_cache_hit_tokens",
+    "optimal_cache_miss_tokens",
+    "optimal_cache_hit_rate",
+    "optimal_cache_block_hit_rate",
+)
+
+
+def build_annotated_trace(
+    trace_data: Dict[str, Any],
+    record: Dict[str, Any],
+) -> Dict[str, Any]:
+    """Return a deep copy of *trace_data* with hit-rate fields added.
+
+    Args:
+        trace_data: Parsed contents of a ``*.trace.json`` file.
+        record: Output from :func:`compute_cache_hit_upper_bound` for the
+            same trace. Each entry in ``record["requests"]`` is matched to
+            an event by its ``event_index``.
+
+    Returns:
+        A new JSON-serializable dict in the same schema as the input
+        trace, with the four annotation fields attached to scored
+        assistant events.
+    """
+    annotated = copy.deepcopy(trace_data)
+    events = annotated.get("events")
+    if not isinstance(events, list):
+        return annotated
+    for request in record.get("requests", []):
+        event_index = request.get("event_index")
+        if not isinstance(event_index, int):
+            continue
+        if event_index < 0 or event_index >= len(events):
+            continue
+        event = events[event_index]
+        if not isinstance(event, dict):
+            continue
+        for field in ANNOTATION_FIELDS:
+            if field in request:
+                event[field] = request[field]
+    return annotated
diff --git a/examples/scaffolding/trace_replay/analysis/blocks.py b/examples/scaffolding/trace_replay/analysis/blocks.py
new file mode 100644
index 000000000000..0dd1fe7d6d09
--- /dev/null
+++ b/examples/scaffolding/trace_replay/analysis/blocks.py
@@ -0,0 +1,138 @@
+r"""Prefix cache primitives for KV-cache hit analysis.
+
+Mirrors TRT-LLM's KV cache accounting so the offline upper bound
+:func:`compute_cache_hit_upper_bound` always dominates the engine-measured
+``num_reused_blocks / (num_reused + num_missed)`` per request.
+
+Key invariants:
+* Every committed sequence contributes ``ceil(L / block)`` blocks (the
+  partial trailing block is hashed by its actual token content, not
+  padding).
+* A future request's reused-block count is
+  ``ceil(matched_tokens / block)``, with ``+1`` on a clean-aligned match
+  (the engine occasionally counts the next block as reused when cache
+  state lets the partial-overlap hash hit). Capped at the request's
+  total block count.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Dict, List, Sequence
+
+
+class _TokenNode:
+    """Compressed-edge radix-tree node, keyed by first token of each child."""
+
+    __slots__ = ("edge_tail", "children")
+
+    def __init__(self, edge_tail: List[int]) -> None:
+        # ``edge_tail`` is the token sequence on the incoming edge AFTER the
+        # first token (which is the key in the parent's children dict).
+        self.edge_tail: List[int] = edge_tail
+        self.children: Dict[int, "_TokenNode"] = {}
+
+
+class TokenPrefixCache:
+    """Infinite-capacity token-level prefix cache.
+
+    Stores arbitrary token sequences and answers ``longest matching prefix``
+    queries in O(L) time, where L = query length. Each ``insert`` adds the
+    full token list; a later ``match`` returns the longest prefix length
+    (in tokens) shared with any previously inserted sequence.
+    """
+
+    def __init__(self) -> None:
+        self._root = _TokenNode([])
+
+    def insert(self, tokens: Sequence[int]) -> None:
+        """Insert *tokens* as a complete sequence."""
+        toks = list(tokens)
+        n = len(toks)
+        if n == 0:
+            return
+        node = self._root
+        i = 0
+        while i < n:
+            first = toks[i]
+            child = node.children.get(first)
+            if child is None:
+                node.children[first] = _TokenNode(toks[i + 1 : n])
+                return
+            tail = child.edge_tail
+            j = 0
+            while j < len(tail) and i + 1 + j < n and tail[j] == toks[i + 1 + j]:
+                j += 1
+            if j == len(tail):
+                node = child
+                i += 1 + j
+                continue
+            # Partial edge match: split the edge into two.
+            new_lower = _TokenNode(tail[j + 1 :])
+            new_lower.children = child.children
+            child.children = {tail[j]: new_lower}
+            child.edge_tail = tail[:j]
+            i += 1 + j
+            if i < n:
+                child.children[toks[i]] = _TokenNode(toks[i + 1 :])
+            return
+
+    def match(self, query: Sequence[int]) -> int:
+        """Return the longest prefix of *query* (in tokens) seen before."""
+        q = list(query)
+        n = len(q)
+        if n == 0:
+            return 0
+        node = self._root
+        matched = 0
+        while matched < n:
+            child = node.children.get(q[matched])
+            if child is None:
+                break
+            tail = child.edge_tail
+            matched += 1
+            j = 0
+            while j < len(tail) and matched + j < n and tail[j] == q[matched + j]:
+                j += 1
+            matched += j
+            if j < len(tail):
+                break
+            node = child
+        return matched
+
+
+def engine_aligned_block_count(token_len: int, tokens_per_block: int) -> int:
+    """Total blocks an engine allocates for a request of *token_len* tokens.
+
+    TRT-LLM counts ``ceil(L / block_size)`` blocks (the trailing partial
+    block is allocated and hashed by its content).
+    """
+    if token_len <= 0:
+        return 0
+    return math.ceil(token_len / tokens_per_block)
+
+
+def engine_aligned_hit_blocks(
+    matched_tokens: int,
+    n_total_blocks: int,
+    tokens_per_block: int,
+) -> int:
+    """Strict upper bound on the engine-reported ``num_reused_blocks``.
+
+    A matched prefix of length M tokens covers ``ceil(M / block)`` blocks.
+    When M lands exactly on a block boundary the engine sometimes also
+    counts the next block (random partial-overlap hash hit, ~0.04% of
+    measurements with KV-cache-aware routing); we always include that
+    extra boundary block so UB >= measured. Capped at ``n_total_blocks``.
+    """
+    if matched_tokens <= 0 or n_total_blocks <= 0:
+        return 0
+    hit = math.ceil(matched_tokens / tokens_per_block)
+    if matched_tokens % tokens_per_block == 0:
+        hit += 1
+    return min(hit, n_total_blocks)
+
+
+def validate_tokens_per_block(tokens_per_block: int) -> None:
+    if tokens_per_block <= 0:
+        raise ValueError(f"tokens_per_block must be positive, got {tokens_per_block}")
diff --git a/examples/scaffolding/trace_replay/analysis/branch_summary.py b/examples/scaffolding/trace_replay/analysis/branch_summary.py
new file mode 100644
index 000000000000..c91276f9824a
--- /dev/null
+++ b/examples/scaffolding/trace_replay/analysis/branch_summary.py
@@ -0,0 +1,155 @@
+r"""Per-branch / per-sub-agent rollups over per-request cache-hit records.
+
+Three groupings are produced from the request list:
+
+* ``by_branch_root``  – first element of ``branch_path`` (or ``"root"`` if the
+  request ran at the top scope). Useful for "Researcher 0 vs 1 vs 2" splits.
+* ``by_branch_depth`` – ``len(branch_path)``. Useful for "ToT depth 1 vs 3".
+* ``by_system_prompt`` – first ``system_prompt_id`` UUID seen on the
+  conversation that owns the request. Useful for "all Researcher turns vs all
+  Compressor turns" without needing extra trace fields.
+
+All rollups are pure functions of the per-request list — no cache state,
+no event ordering required.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, List, Optional, Sequence
+
+_NO_SYSTEM_KEY = "(no system)"
+_ROOT_KEY = "root"
+
+
+def compute_branch_rollups(
+    requests: Sequence[Dict[str, Any]],
+) -> Dict[str, List[Dict[str, Any]]]:
+    """Return all three rollups for *requests*."""
+    return {
+        "by_branch_root": _rollup(requests, _branch_root_key),
+        "by_branch_depth": _rollup(requests, _branch_depth_key, sort_numeric=True),
+        "by_system_prompt": _rollup(requests, _system_prompt_key),
+    }
+
+
+def _branch_root_key(req: Dict[str, Any]) -> str:
+    branch_path = req.get("branch_path") or []
+    if not branch_path:
+        return _ROOT_KEY
+    return f"branch:{branch_path[0]}"
+
+
+def _branch_depth_key(req: Dict[str, Any]) -> str:
+    branch_path = req.get("branch_path") or []
+    return f"depth:{len(branch_path)}"
+
+
+def _system_prompt_key(req: Dict[str, Any]) -> str:
+    seed: Optional[str] = req.get("system_prompt_id_seed")
+    if not seed:
+        return _NO_SYSTEM_KEY
+    return f"uuid:{seed}"
+
+
+def _rollup(
+    requests: Sequence[Dict[str, Any]],
+    key_fn: Callable[[Dict[str, Any]], str],
+    *,
+    sort_numeric: bool = False,
+) -> List[Dict[str, Any]]:
+    """Group *requests* by ``key_fn``, return one summary dict per group."""
+    grouped: Dict[str, List[Dict[str, Any]]] = {}
+    for req in requests:
+        grouped.setdefault(key_fn(req), []).append(req)
+
+    summaries = [_group_summary(key, group) for key, group in grouped.items()]
+    if sort_numeric:
+        summaries.sort(key=lambda s: _numeric_suffix(s["group_key"]))
+    else:
+        summaries.sort(key=lambda s: s["group_key"])
+    return summaries
+
+
+def _group_summary(group_key: str, group: List[Dict[str, Any]]) -> Dict[str, Any]:
+    total_prompt_tokens = sum(r["prompt_tokens"] for r in group)
+    total_hit_blocks = sum(r["optimal_cache_hit_blocks"] for r in group)
+    total_miss_blocks = sum(r["optimal_cache_miss_blocks"] for r in group)
+    total_hit_tokens = sum(r["optimal_cache_hit_tokens"] for r in group)
+    total_miss_tokens = sum(r["optimal_cache_miss_tokens"] for r in group)
+    block_total = total_hit_blocks + total_miss_blocks
+    return {
+        "group_key": group_key,
+        "request_count": len(group),
+        "total_prompt_tokens": total_prompt_tokens,
+        "optimal_total_cache_hit_blocks": total_hit_blocks,
+        "optimal_total_cache_miss_blocks": total_miss_blocks,
+        "optimal_total_cache_hit_tokens": total_hit_tokens,
+        "optimal_total_cache_miss_tokens": total_miss_tokens,
+        "optimal_overall_cache_hit_rate": _safe_div(total_hit_tokens, total_prompt_tokens),
+        "optimal_overall_cache_block_hit_rate": _safe_div(total_hit_blocks, block_total),
+    }
+
+
+def merge_rollup_arrays(
+    rollups: Sequence[List[Dict[str, Any]]],
+    *,
+    sort_numeric: bool = False,
+) -> List[Dict[str, Any]]:
+    """Merge per-trace rollup arrays of the same kind into one dataset rollup.
+
+    Groups are matched by ``group_key``; numeric totals are summed and rates
+    recomputed from the sums.
+    """
+    aggregated: Dict[str, Dict[str, int]] = {}
+    for trace_rollup in rollups:
+        for entry in trace_rollup:
+            key = entry["group_key"]
+            slot = aggregated.setdefault(
+                key,
+                {
+                    "request_count": 0,
+                    "total_prompt_tokens": 0,
+                    "optimal_total_cache_hit_blocks": 0,
+                    "optimal_total_cache_miss_blocks": 0,
+                    "optimal_total_cache_hit_tokens": 0,
+                    "optimal_total_cache_miss_tokens": 0,
+                },
+            )
+            for field in slot:
+                slot[field] += entry[field]
+
+    summaries: List[Dict[str, Any]] = []
+    for key, slot in aggregated.items():
+        block_total = (
+            slot["optimal_total_cache_hit_blocks"] + slot["optimal_total_cache_miss_blocks"]
+        )
+        summaries.append(
+            {
+                "group_key": key,
+                **slot,
+                "optimal_overall_cache_hit_rate": _safe_div(
+                    slot["optimal_total_cache_hit_tokens"], slot["total_prompt_tokens"]
+                ),
+                "optimal_overall_cache_block_hit_rate": _safe_div(
+                    slot["optimal_total_cache_hit_blocks"], block_total
+                ),
+            }
+        )
+    if sort_numeric:
+        summaries.sort(key=lambda s: _numeric_suffix(s["group_key"]))
+    else:
+        summaries.sort(key=lambda s: s["group_key"])
+    return summaries
+
+
+def _numeric_suffix(group_key: str) -> int:
+    """Sort key for ``depth:N`` / ``branch:N`` style identifiers."""
+    _, _, tail = group_key.partition(":")
+    try:
+        return int(tail)
+    except ValueError:
+        return -1
+
+
+def _safe_div(num: float, denom: float) -> float:
+    return num / denom if denom else 0.0
diff --git a/examples/scaffolding/trace_replay/analysis/cache_hit.py b/examples/scaffolding/trace_replay/analysis/cache_hit.py
new file mode 100644
index 000000000000..03f2ef4789ec
--- /dev/null
+++ b/examples/scaffolding/trace_replay/analysis/cache_hit.py
@@ -0,0 +1,520 @@
+r"""Per-trace KV-cache hit upper-bound computation.
+
+The single public entry point :func:`compute_cache_hit_upper_bound` takes a
+parsed trace and returns a JSON-serializable record of per-request hit/miss
+statistics, an aggregate summary, and per-(branch / depth / system-prompt)
+rollups suitable for analyzing branched / parallel sub-agent workflows
+(ToT, Open Deep Research).
+
+Strict mode contract (this analyzer):
+
+* Every ``role=system`` event MUST carry a non-empty ``system_prompt_id``
+  UUID. Untagged system events are an error.
+* ``drop_kv_cache`` events are an error — this analyzer assumes no eviction.
+* All branches in the trace share a single global token prefix cache
+  (the most permissive UB).
+
+Algorithm:
+
+1. **Pre-warm phase.** Walk the trace once to discover every distinct
+   ``system_prompt_id``. Allocate a synthetic token sequence per UUID
+   (longest length seen) and pre-insert its full blocks into the radix
+   tree. Every block fully covered by a known system prompt is then a
+   guaranteed cache hit on first request.
+
+2. **Scoring phase.** Walk events in order, mirroring
+   :class:`tensorrt_llm.scaffolding.trace_replay.replay.QueueExecutor`: per
+   ``(branch_path, conversation_id)`` keep a list of segments indexed by
+   ``message_index``. System segments draw tokens from the shared registry
+   (cross-conversation reuse exact). User/tool/assistant-content segments
+   use fresh allocator tokens. For each assistant request, assemble the
+   prompt by concatenating segments, score it against the prefix tree,
+   then optionally store the decode-time sequence into the cache when
+   ``decode_kv_reuse=True``. With ``cot_pollutes_cache=True`` (default),
+   the stored sequence is ``[prompt + reasoning + content]`` — reasoning
+   token IDs are minted fresh and live only in the cache, never in the
+   segment store, so future-turn prompts assembled from segments diverge
+   from the cached prefix at the reasoning-insertion block (mirroring
+   real TRT-LLM C++ KV manager behavior). With ``cot_pollutes_cache=False``
+   the stored sequence is just ``[prompt + content]`` — the optimistic
+   upper bound that treats reasoning as if it never occupied KV.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Dict, List, MutableMapping, Optional, Sequence
+
+from .blocks import (
+    TokenPrefixCache,
+    engine_aligned_block_count,
+    engine_aligned_hit_blocks,
+    validate_tokens_per_block,
+)
+from .branch_summary import compute_branch_rollups
+from .streams import ConversationSegments, SystemPromptRegistry, TokenIdAllocator
+
+SCHEMA = "scaffolding.cache_hit_trace.v6"
+
+
+def compute_cache_hit_upper_bound(
+    trace_data: Dict[str, Any],
+    *,
+    tokens_per_block: int = 32,
+    decode_kv_reuse: bool = True,
+    cot_pollutes_cache: bool = True,
+    include_rollups: bool = True,
+    trace_file: Any = None,
+) -> Dict[str, Any]:
+    """Compute the infinite-cache prefix-hit upper bound for one trace.
+
+    The result is a strict upper bound on every per-request
+    ``optimal_cache_block_hit_rate`` an in-line TRT-LLM engine can achieve
+    when replaying the trace via
+    ``tensorrt_llm.scaffolding.trace_replay.replay.QueueExecutor`` against
+    ``/v1/completions``.
+
+    Args:
+        trace_data: Parsed contents of a ``*.trace.json`` file.
+        tokens_per_block: KV-cache block size in tokens.
+        decode_kv_reuse: When ``True`` (default), assistant decode tokens
+            are inserted into the cache and may be reused as a prefix by
+            later requests in the same conversation. When ``False``, decode
+            tokens are still recorded in the conversation's segment list
+            (so subsequent ``prompt_tokens`` reconciliation is correct) but
+            are NOT inserted into the cache — modeling a deployment where
+            decode-phase KV is dropped after the request.
+        cot_pollutes_cache: Only meaningful when ``decode_kv_reuse=True``.
+            When ``True`` (default), model real TRT-LLM C++ KV manager
+            behavior: the decode-time KV stream stored in the radix tree
+            is ``[prompt + reasoning + content]``, with reasoning occupying
+            distinct positions between prompt and content. Subsequent
+            turns whose prompts omit prior reasoning (the only thing
+            scaffolding ever feeds back) then diverge from the cached
+            prefix at the reasoning-insertion block, causing miss
+            propagation through every block after it. When ``False``,
+            fall back to the optimistic upper bound where reasoning is
+            assumed absent from the cache: only ``[prompt + content]`` is
+            inserted, so a later turn can hit through to the end of
+            content. The gap between the two modes quantifies the KV
+            cache waste caused by reasoning tokens.
+        include_rollups: When ``True`` (default), compute per-(branch root /
+            branch depth / system-prompt UUID) rollups.
+        trace_file: Optional path-like value placed verbatim in the output.
+
+    Returns:
+        A JSON-serializable dictionary with ``schema``, ``algorithm``,
+        ``summary``, ``requests`` and (optionally) ``rollups`` fields.
+    """
+    validate_tokens_per_block(tokens_per_block)
+
+    events = trace_data.get("events", [])
+    if not isinstance(events, list):
+        raise ValueError("Trace events must be a list")
+
+    _reject_unsupported_events(events)
+
+    allocator = TokenIdAllocator()
+    system_registry = SystemPromptRegistry(allocator)
+    segments = ConversationSegments(allocator, system_registry)
+    prefix_cache = TokenPrefixCache()
+    cached_block_count = [0]  # mutable cell so helpers can read/update
+
+    def _commit_stream(token_ids):
+        """Insert *token_ids* and update the running committed-block count.
+
+        Uses engine-aligned ``ceil(L / block)`` block accounting. The token
+        sequence itself is stored in the radix tree so future requests can
+        match at single-token granularity (a partial trailing block hits
+        when its content matches).
+        """
+        if not token_ids:
+            return 0
+        before = cached_block_count[0]
+        cached_block_count[0] = max(
+            before, engine_aligned_block_count(len(token_ids), tokens_per_block)
+        )
+        prefix_cache.insert(token_ids)
+        return cached_block_count[0] - before
+
+    # ---- Phase 1: pre-warm cache with every system prompt template. ----
+    # Each distinct system_prompt_id contributes its full ceil(L/block)
+    # blocks (matching the engine's commit count once the very first
+    # request that uses it lands in the radix tree).
+    system_prefix_lengths = _collect_system_prefix_lengths(events)
+    for uuid_, length in system_prefix_lengths.items():
+        token_ids = system_registry.tokens(uuid_, length)
+        _commit_stream(token_ids)
+    preloaded_system_blocks = cached_block_count[0]
+
+    # ---- Phase 2: score each assistant request against the prefix tree. ----
+    requests: List[Dict[str, Any]] = []
+    totals = _Totals()
+
+    for event_index, event in enumerate(events):
+        if not isinstance(event, dict):
+            raise ValueError(f"Event {event_index} is not an object: {event!r}")
+        if event.get("event_type") != "message":
+            continue
+
+        role = event.get("role")
+        branch_path = _branch_path(event)
+        conversation_id = event.get("conversation_id")
+        if not isinstance(conversation_id, int):
+            raise ValueError(
+                f"Event {event_index} has invalid conversation_id: {conversation_id!r}"
+            )
+        message_index = event.get("message_index")
+
+        if role == "system":
+            system_prompt_id = event.get("system_prompt_id")
+            if not system_prompt_id:
+                raise ValueError(
+                    f"Event {event_index}: system message has no "
+                    "system_prompt_id (strict mode requires UUID-tagged "
+                    "system prompts)"
+                )
+            token_count = _as_nonnegative_int(event.get("tokens", 0), "tokens", event_index)
+            segments.record_system(
+                branch_path,
+                conversation_id,
+                message_index,
+                system_prompt_id,
+                token_count,
+            )
+            continue
+
+        if role in ("user", "tool"):
+            token_count = _as_nonnegative_int(event.get("tokens", 0), "tokens", event_index)
+            segments.record_user_or_tool(branch_path, conversation_id, message_index, token_count)
+            continue
+
+        if role != "assistant" or "prompt_tokens" not in event:
+            continue
+
+        request = _score_assistant_event(
+            event=event,
+            event_index=event_index,
+            branch_path=branch_path,
+            conversation_id=conversation_id,
+            message_index=message_index,
+            segments=segments,
+            prefix_cache=prefix_cache,
+            commit_stream=_commit_stream,
+            cached_block_count_cell=cached_block_count,
+            tokens_per_block=tokens_per_block,
+            decode_kv_reuse=decode_kv_reuse,
+            cot_pollutes_cache=cot_pollutes_cache,
+            request_index=len(requests),
+        )
+        requests.append(request)
+        totals.add(request)
+
+    rollups = compute_branch_rollups(requests) if include_rollups else None
+    return _build_record(
+        trace_data=trace_data,
+        trace_file=trace_file,
+        events=events,
+        requests=requests,
+        rollups=rollups,
+        totals=totals,
+        cached_blocks=cached_block_count[0],
+        preloaded_system_blocks=preloaded_system_blocks,
+        distinct_system_prompts=len(system_prefix_lengths),
+        tokens_per_block=tokens_per_block,
+        decode_kv_reuse=decode_kv_reuse,
+        cot_pollutes_cache=cot_pollutes_cache,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Internals
+# ---------------------------------------------------------------------------
+
+
+class _Totals:
+    """Running sums across requests for a single trace."""
+
+    def __init__(self) -> None:
+        self.prompt_tokens = 0
+        self.hit_tokens = 0
+        self.hit_blocks = 0
+        self.miss_blocks = 0
+
+    def add(self, request: Dict[str, Any]) -> None:
+        self.prompt_tokens += request["prompt_tokens"]
+        self.hit_tokens += request["optimal_cache_hit_tokens"]
+        self.hit_blocks += request["optimal_cache_hit_blocks"]
+        self.miss_blocks += request["optimal_cache_miss_blocks"]
+
+
+def _score_assistant_event(
+    *,
+    event: Dict[str, Any],
+    event_index: int,
+    branch_path: Sequence[int],
+    conversation_id: int,
+    message_index: Optional[int],
+    segments: ConversationSegments,
+    prefix_cache: TokenPrefixCache,
+    commit_stream,
+    cached_block_count_cell,
+    tokens_per_block: int,
+    decode_kv_reuse: bool,
+    cot_pollutes_cache: bool,
+    request_index: int,
+) -> Dict[str, Any]:
+    """Score a single assistant message event with engine-aligned accounting.
+
+    Block counting follows the TRT-LLM engine exactly:
+      * total blocks for the request = ``ceil(L_effective / block)``
+      * reused blocks = ``min(ceil(matched_tokens / block), total)``
+      * ``L_effective`` = length of segments concatenated in trace order
+        (i.e., what ``QueueExecutor`` actually sends to the engine via
+        ``/v1/completions`` as ``prompt=List[int]``). This may differ from
+        the trace's recorded ``prompt_tokens`` field, which carries the
+        original recording API's chat-template-formatted count.
+    """
+    trace_prompt_tokens = _as_nonnegative_int(
+        event.get("prompt_tokens") or 0, "prompt_tokens", event_index
+    )
+    completion_tokens = _as_nonnegative_int(
+        event.get("completion_tokens") or 0, "completion_tokens", event_index
+    )
+    reasoning_tokens = _as_nonnegative_int(
+        event.get("reasoning_tokens") or 0, "reasoning_tokens", event_index
+    )
+
+    # Effective prompt = exactly what the replay engine sends.
+    prompt_token_ids = segments.assemble_prompt(branch_path, conversation_id)
+    effective_prompt_tokens = len(prompt_token_ids)
+    n_total_blocks = engine_aligned_block_count(effective_prompt_tokens, tokens_per_block)
+
+    matched_tokens = prefix_cache.match(prompt_token_ids)
+    hit_blocks = engine_aligned_hit_blocks(matched_tokens, n_total_blocks, tokens_per_block)
+    miss_blocks = n_total_blocks - hit_blocks
+
+    hit_tokens = min(matched_tokens, effective_prompt_tokens)
+    miss_tokens = effective_prompt_tokens - hit_tokens
+    optimal_cache_block_hit_rate = hit_blocks / n_total_blocks if n_total_blocks else 0.0
+    optimal_cache_hit_rate = (
+        hit_tokens / effective_prompt_tokens if effective_prompt_tokens else 0.0
+    )
+
+    # The new prompt is committed first (so its own block count contributes
+    # to ``cached_blocks_after_request``), then decode tokens extend it.
+    new_cached_prompt_blocks = commit_stream(prompt_token_ids)
+
+    # Decode-time storage: same semantics as before. Reasoning is hidden from
+    # future-turn prompt assembly but is inserted into the radix tree under
+    # ``cot_pollutes_cache=True`` to mirror the C++ KV manager.
+    content_tokens = max(completion_tokens - reasoning_tokens, 0)
+    if content_tokens > 0:
+        segments.record_assistant_content(
+            branch_path, conversation_id, message_index, content_tokens
+        )
+
+    cached_before_completion = cached_block_count_cell[0]
+    if decode_kv_reuse and completion_tokens > 0:
+        if cot_pollutes_cache and reasoning_tokens > 0:
+            reasoning_token_ids = segments.allocate_tokens(reasoning_tokens)
+            if content_tokens > 0:
+                content_token_ids = segments.assemble_prompt(branch_path, conversation_id)[
+                    effective_prompt_tokens:
+                ]
+            else:
+                content_token_ids = []
+            decode_stream = list(prompt_token_ids) + reasoning_token_ids + content_token_ids
+            commit_stream(decode_stream)
+        elif content_tokens > 0:
+            tail_prompt = segments.assemble_prompt(branch_path, conversation_id)
+            commit_stream(tail_prompt)
+    new_cached_completion_blocks = cached_block_count_cell[0] - cached_before_completion
+    new_cached_blocks = new_cached_prompt_blocks + new_cached_completion_blocks
+
+    seed_uuid = segments.seed_uuid_for(branch_path, conversation_id)
+    branch_path_list = list(branch_path)
+    return {
+        "request_index": request_index,
+        "event_index": event_index,
+        "conversation_id": conversation_id,
+        "branch_path": branch_path_list,
+        "branch_root": branch_path_list[0] if branch_path_list else None,
+        "branch_depth": len(branch_path_list),
+        "system_prompt_id_seed": seed_uuid,
+        "message_index": message_index,
+        # ``prompt_tokens`` mirrors the engine-visible length (effective).
+        # The trace's original recorded value is exposed separately under
+        # ``trace_prompt_tokens`` for cross-checks.
+        "prompt_tokens": effective_prompt_tokens,
+        "trace_prompt_tokens": trace_prompt_tokens,
+        "tokens_per_block": tokens_per_block,
+        "matched_prompt_tokens": min(matched_tokens, effective_prompt_tokens),
+        "optimal_cache_hit_blocks": hit_blocks,
+        "optimal_cache_miss_blocks": miss_blocks,
+        "optimal_cache_hit_tokens": hit_tokens,
+        "optimal_cache_miss_tokens": miss_tokens,
+        "optimal_cache_hit_rate": optimal_cache_hit_rate,
+        "optimal_cache_block_hit_rate": optimal_cache_block_hit_rate,
+        "new_cached_prompt_blocks": new_cached_prompt_blocks,
+        "new_cached_completion_blocks": new_cached_completion_blocks,
+        "new_cached_blocks": new_cached_blocks,
+        "new_cached_tokens": new_cached_blocks * tokens_per_block,
+        "cached_blocks_after_request": cached_block_count_cell[0],
+        "cached_tokens_after_request": cached_block_count_cell[0] * tokens_per_block,
+        "completion_tokens": completion_tokens,
+        "reasoning_tokens": reasoning_tokens,
+        "reusable_completion_tokens": content_tokens,
+        "finish_reason": event.get("finish_reason"),
+        "tool_calls": event.get("tool_calls", []),
+    }
+
+
+def _reject_unsupported_events(events: List[Any]) -> None:
+    """Raise on any event type the strict-mode analyzer cannot model."""
+    for event_index, event in enumerate(events):
+        if not isinstance(event, dict):
+            continue
+        event_type = event.get("event_type")
+        if event_type == "drop_kv_cache":
+            raise ValueError(
+                f"Event {event_index}: drop_kv_cache events are not "
+                "supported by this analyzer (it assumes an infinite, "
+                "non-evicting cache)"
+            )
+
+
+def _collect_system_prefix_lengths(events: Sequence[Any]) -> Dict[str, int]:
+    """Largest ``tokens`` seen per ``system_prompt_id`` across the trace."""
+    lengths: Dict[str, int] = {}
+    for event_index, event in enumerate(events):
+        if not isinstance(event, dict):
+            continue
+        if event.get("event_type") != "message" or event.get("role") != "system":
+            continue
+        system_prompt_id = event.get("system_prompt_id")
+        if not system_prompt_id:
+            raise ValueError(
+                f"Event {event_index}: system message has no system_prompt_id "
+                "(strict mode requires UUID-tagged system prompts)"
+            )
+        token_count = event.get("tokens") or 0
+        if not isinstance(token_count, int) or token_count <= 0:
+            continue
+        prev = lengths.get(system_prompt_id, 0)
+        if token_count > prev:
+            lengths[system_prompt_id] = token_count
+    return lengths
+
+
+def _branch_path(event: MutableMapping[str, Any]) -> List[int]:
+    raw = event.get("branch_path", [])
+    if not isinstance(raw, list) or not all(isinstance(x, int) for x in raw):
+        raise ValueError(f"Invalid branch_path: {raw!r}")
+    return raw
+
+
+def _as_nonnegative_int(value: Any, field_name: str, event_index: int) -> int:
+    if value is None:
+        return 0
+    if not isinstance(value, int):
+        raise ValueError(f"Event {event_index} has non-integer {field_name}: {value!r}")
+    if value < 0:
+        raise ValueError(f"Event {event_index} has negative {field_name}: {value}")
+    return value
+
+
+def _build_record(
+    *,
+    trace_data: Dict[str, Any],
+    trace_file: Any,
+    events: List[Any],
+    requests: List[Dict[str, Any]],
+    rollups: Optional[Dict[str, List[Dict[str, Any]]]],
+    totals: _Totals,
+    cached_blocks: int,
+    preloaded_system_blocks: int,
+    distinct_system_prompts: int,
+    tokens_per_block: int,
+    decode_kv_reuse: bool,
+    cot_pollutes_cache: bool,
+) -> Dict[str, Any]:
+    optimal_overall_cache_hit_rate = (
+        totals.hit_tokens / totals.prompt_tokens if totals.prompt_tokens else 0.0
+    )
+    block_total = totals.hit_blocks + totals.miss_blocks
+    optimal_overall_cache_block_hit_rate = totals.hit_blocks / block_total if block_total else 0.0
+    record: Dict[str, Any] = {
+        "schema": SCHEMA,
+        "created_at_utc": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+        "trace_file": str(trace_file) if trace_file is not None else None,
+        "trace_id": trace_data.get("trace_id"),
+        "algorithm": {
+            "cache_model": "infinite_token_radix_tree_engine_aligned",
+            "preloaded_system_prompts": True,
+            "tokens_per_block": tokens_per_block,
+            "decode_kv_reuse": decode_kv_reuse,
+            "cot_pollutes_cache": cot_pollutes_cache,
+            "parallel_policy": "shared",
+            "request_definition": (
+                "assistant message events; prompt length = natural "
+                "concatenation of stored segments (matches replay engine's "
+                "/v1/completions input_tokens length)"
+            ),
+            "hit_definition": (
+                "n_total_blocks = ceil(L_effective / block); "
+                "reused_blocks = min(ceil(matched_tokens / block), n_total_blocks). "
+                "Matches the TRT-LLM engine, whose KV cache hashes the partial "
+                "trailing block by its actual content so the upper bound "
+                "dominates every measured num_reused_blocks."
+            ),
+            "strict_mode": (
+                "Every system message must carry a system_prompt_id UUID; "
+                "drop_kv_cache events are rejected."
+            ),
+            "note": (
+                "Phase 1 inserts every distinct system prompt's full token "
+                "stream into a token-level radix tree (compressed-edge), so "
+                "the first request hitting that template reuses ceil(L/block) "
+                "blocks regardless of partial-block alignment. Phase 2 walks "
+                "the trace event-by-event, accumulating per-(branch_path, "
+                "conversation_id) message segments — system slices share a "
+                "UUID-keyed token stream; user/tool/assistant-content use "
+                "fresh synthetic IDs. Reasoning tokens are excluded from "
+                "assistant content in the segment store because scaffolding "
+                "does not feed hidden reasoning back. When cot_pollutes_cache "
+                "is True (default), the decode-time stream inserted into the "
+                "tree is [prompt + reasoning + content] with reasoning at "
+                "distinct token IDs, mirroring the C++ KV manager; subsequent "
+                "turns diverge from the cached prefix at the reasoning "
+                "boundary. When False, only [prompt + content] is stored — "
+                "the optimistic upper bound. decode_kv_reuse=False discards "
+                "decode-phase KV (segments still grow so prompt assembly "
+                "stays consistent). All branches share a single global cache."
+            ),
+        },
+        "summary": {
+            "event_count": len(events),
+            "llm_request_count": len(requests),
+            "tokens_per_block": tokens_per_block,
+            "decode_kv_reuse": decode_kv_reuse,
+            "cot_pollutes_cache": cot_pollutes_cache,
+            "distinct_system_prompts": distinct_system_prompts,
+            "preloaded_system_blocks": preloaded_system_blocks,
+            "preloaded_system_tokens": preloaded_system_blocks * tokens_per_block,
+            "total_prompt_tokens": totals.prompt_tokens,
+            "optimal_total_cache_hit_blocks": totals.hit_blocks,
+            "optimal_total_cache_miss_blocks": totals.miss_blocks,
+            "optimal_total_cache_hit_tokens": totals.hit_tokens,
+            "optimal_total_cache_miss_tokens": totals.prompt_tokens - totals.hit_tokens,
+            "optimal_overall_cache_hit_rate": optimal_overall_cache_hit_rate,
+            "optimal_overall_cache_block_hit_rate": optimal_overall_cache_block_hit_rate,
+            "minimal_cache_blocks": cached_blocks,
+            "minimal_cache_tokens": cached_blocks * tokens_per_block,
+            "max_prompt_tokens": max((req["prompt_tokens"] for req in requests), default=0),
+        },
+        "requests": requests,
+    }
+    if rollups is not None:
+        record["rollups"] = rollups
+    return record
diff --git a/examples/scaffolding/trace_replay/analysis/compute_cache_hit_trace.py b/examples/scaffolding/trace_replay/analysis/compute_cache_hit_trace.py
new file mode 100644
index 000000000000..eb5edf5f26fe
--- /dev/null
+++ b/examples/scaffolding/trace_replay/analysis/compute_cache_hit_trace.py
@@ -0,0 +1,174 @@
+r"""CLI: compute the ideal prefix KV-cache hit upper bound for scaffolding traces.
+
+Typical usage::
+
+    python examples/scaffolding/trace_replay/analysis/compute_cache_hit_trace.py \
+        TRACES/swebench-verified/coder/astropy__astropy-7166
+
+The input may be a trace directory, a specific ``*.trace.json`` file, a
+directory containing multiple traces, or a dataset directory whose immediate
+subdirectories each contain one trace. Default output is
+``<trace_name>.cachehit.json`` next to the input trace; for dataset inputs an
+extra ``<dataset_name>.cachehit.json`` summary is also written.
+
+This script is a thin wrapper around
+:func:`analysis.compute_cache_hit_upper_bound`. The simulation pre-loads all
+distinct system prompt templates (keyed by ``system_prompt_id`` UUID) into
+the radix tree before any request is scored, so all blocks of a system
+prompt are 100%% cache hits regardless of which conversation issues them.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+# Make the containing ``analysis`` package importable when this script is run
+# directly (``python examples/scaffolding/trace_replay/analysis/compute_cache_hit_trace.py``).
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from analysis import (  # noqa: E402  (import after sys.path tweak)
+    aggregate_dataset_record,
+    build_annotated_trace,
+    compute_cache_hit_upper_bound,
+    default_annotated_trace_path,
+    default_dataset_output_path,
+    default_output_path,
+    load_trace,
+    resolve_input_trace_files,
+    write_json,
+)
+
+
+def _parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description=(
+            "Compute the ideal infinite-KV-cache prefix hit upper bound for "
+            "one scaffolding trace, or for all traces in a directory / "
+            "dataset. All distinct system prompt templates discovered in the "
+            "trace are pre-loaded into the cache before scoring."
+        )
+    )
+    parser.add_argument(
+        "trace",
+        type=Path,
+        help=(
+            "Input trace directory, directory of traces, dataset directory of "
+            "trace subdirectories, or a specific *.trace.json file."
+        ),
+    )
+    parser.add_argument(
+        "--output-json",
+        type=Path,
+        default=None,
+        help="Output JSON path. Default: <trace_name>.cachehit.json.",
+    )
+    parser.add_argument(
+        "--tokens-per-block",
+        type=int,
+        default=32,
+        help=(
+            "Number of tokens in one KV-cache block. The current PyTorch "
+            "KvCacheConfig and serve router default to 32; legacy TensorRT "
+            "builds often use 64."
+        ),
+    )
+    parser.add_argument(
+        "--decode-kv-reuse",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help=(
+            "When enabled (default), assistant decode tokens are inserted "
+            "into the cache and may be reused as a prefix by later requests "
+            "in the same conversation. Pass --no-decode-kv-reuse to model a "
+            "deployment that drops decode-phase KV after each request "
+            "(decode tokens still grow the conversation's prompt for later "
+            "turns; they just no longer hit cache)."
+        ),
+    )
+    parser.add_argument(
+        "--cot-pollutes-cache",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help=(
+            "When enabled (default), model real TRT-LLM C++ KV manager "
+            "behavior: the decode-time KV stream stored in the radix tree "
+            "is [prompt + reasoning + content], so future turns whose "
+            "prompts omit prior reasoning diverge from the cached prefix "
+            "at the reasoning-insertion block. Pass --no-cot-pollutes-cache "
+            "for the optimistic upper bound where reasoning is treated as "
+            "if it never occupied any KV position (only [prompt + content] "
+            "is stored). Only meaningful when --decode-kv-reuse is on."
+        ),
+    )
+    parser.add_argument(
+        "--no-rollups",
+        action="store_true",
+        help=("Skip per-branch / per-depth / per-system-prompt rollups in the output."),
+    )
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = _parse_args()
+    trace_files, is_dataset = resolve_input_trace_files(args.trace)
+    trace_data_list = [load_trace(trace_file) for trace_file in trace_files]
+    trace_records = [
+        compute_cache_hit_upper_bound(
+            trace_data,
+            tokens_per_block=args.tokens_per_block,
+            decode_kv_reuse=args.decode_kv_reuse,
+            cot_pollutes_cache=args.cot_pollutes_cache,
+            include_rollups=not args.no_rollups,
+            trace_file=trace_file,
+        )
+        for trace_file, trace_data in zip(trace_files, trace_data_list)
+    ]
+
+    # Always emit a per-trace ``*.trace.cachehit.json`` next to each input
+    # trace: a deep copy of the original trace with four hit-rate fields
+    # attached to each scored assistant event.
+    annotated_paths = []
+    for trace_file, trace_data, record in zip(trace_files, trace_data_list, trace_records):
+        annotated_path = default_annotated_trace_path(trace_file)
+        write_json(annotated_path, build_annotated_trace(trace_data, record))
+        annotated_paths.append(annotated_path)
+
+    if is_dataset:
+        output_json = default_dataset_output_path(args.trace, args.output_json)
+        per_trace_paths = [default_output_path(t, None) for t in trace_files]
+        if output_json in per_trace_paths:
+            raise ValueError(
+                f"Dataset output path collides with a per-trace output path: "
+                f"{output_json}. Use --output-json to choose a different "
+                "dataset summary path."
+            )
+        for path, record in zip(per_trace_paths, trace_records):
+            write_json(path, record)
+        record = aggregate_dataset_record(trace_records)
+    else:
+        output_json = default_output_path(trace_files[0], args.output_json)
+        record = trace_records[0]
+
+    write_json(output_json, record)
+    print(f"Wrote {output_json}")
+    for annotated_path in annotated_paths:
+        print(f"Wrote {annotated_path}")
+    summary = dict(record if is_dataset else record["summary"])
+    summary.setdefault("trace_count", 1)
+    print(
+        "traces={trace_count} llm_requests={llm_request_count} "
+        "tokens_per_block={tokens_per_block} "
+        "preloaded_system_blocks={preloaded_system_blocks} "
+        "minimal_cache_blocks={minimal_cache_blocks} "
+        "optimal_overall_cache_hit_rate={optimal_overall_cache_hit_rate:.6f}".format(**summary)
+    )
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        raise SystemExit(1) from exc
diff --git a/examples/scaffolding/trace_replay/analysis/io.py b/examples/scaffolding/trace_replay/analysis/io.py
new file mode 100644
index 000000000000..5526f4d2c74b
--- /dev/null
+++ b/examples/scaffolding/trace_replay/analysis/io.py
@@ -0,0 +1,108 @@
+"""Filesystem helpers: locate trace files, load/write JSON."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+OUTPUT_SUFFIX = ".cachehit.json"
+ANNOTATED_TRACE_SUFFIX = ".trace.cachehit.json"
+
+
+def load_trace(path: Path) -> Dict[str, Any]:
+    with path.open("r", encoding="utf-8") as f:
+        data = json.load(f)
+    if not isinstance(data, dict):
+        raise ValueError(f"Trace JSON must contain an object: {path}")
+    return data
+
+
+def write_json(path: Path, record: Dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp_path = path.with_suffix(path.suffix + ".tmp")
+    with tmp_path.open("w", encoding="utf-8") as f:
+        json.dump(record, f, indent=2, ensure_ascii=False)
+        f.write("\n")
+    tmp_path.replace(path)
+
+
+def _trace_files_in_directory(trace_dir: Path) -> List[Path]:
+    candidates = sorted(trace_dir.glob("*.trace.json"))
+    compact = [p for p in candidates if not p.name.endswith(".full.trace.json")]
+    return compact or candidates
+
+
+def resolve_trace_file(trace_path: Path) -> Path:
+    trace_path = trace_path.expanduser().resolve()
+    if trace_path.is_file():
+        return trace_path
+    if not trace_path.is_dir():
+        raise FileNotFoundError(f"Trace path does not exist: {trace_path}")
+    candidates = _trace_files_in_directory(trace_path)
+    if len(candidates) == 1:
+        return candidates[0]
+    if not candidates:
+        raise FileNotFoundError(f"No *.trace.json file found in {trace_path}")
+    raise ValueError(f"Multiple trace files found in {trace_path}: {candidates}")
+
+
+def resolve_input_trace_files(trace_path: Path) -> Tuple[List[Path], bool]:
+    """Return ``(trace_files, is_dataset)`` for *trace_path*.
+
+    Inputs supported:
+      - a specific ``*.trace.json`` file → ``([file], False)``
+      - a directory containing exactly one trace → ``([file], False)``
+      - a directory containing several traces → all of them, ``True``
+      - a dataset directory whose subdirs each contain one trace → all, ``True``
+    """
+    trace_path = trace_path.expanduser().resolve()
+    if trace_path.is_file():
+        return [trace_path], False
+    if not trace_path.is_dir():
+        raise FileNotFoundError(f"Trace path does not exist: {trace_path}")
+
+    trace_files = _trace_files_in_directory(trace_path)
+    if trace_files:
+        return trace_files, len(trace_files) > 1
+
+    skipped: List[Path] = []
+    for child in sorted(trace_path.iterdir()):
+        if not child.is_dir():
+            continue
+        try:
+            trace_files.append(resolve_trace_file(child))
+        except FileNotFoundError:
+            skipped.append(child)
+    if trace_files:
+        return trace_files, True
+    if skipped:
+        raise FileNotFoundError(
+            f"No trace files found in dataset directory {trace_path}; "
+            f"checked {len(skipped)} subdirectories"
+        )
+    raise FileNotFoundError(f"No *.trace.json file found in {trace_path}")
+
+
+def default_output_path(trace_file: Path, output_json: Optional[Path]) -> Path:
+    if output_json is not None:
+        return output_json.expanduser().resolve()
+    if trace_file.name.endswith(".trace.json"):
+        return trace_file.with_name(trace_file.name[: -len(".trace.json")] + OUTPUT_SUFFIX)
+    return trace_file.with_suffix(OUTPUT_SUFFIX)
+
+
+def default_dataset_output_path(dataset_dir: Path, output_json: Optional[Path]) -> Path:
+    if output_json is not None:
+        return output_json.expanduser().resolve()
+    resolved = dataset_dir.expanduser().resolve()
+    return resolved / f"{resolved.name}{OUTPUT_SUFFIX}"
+
+
+def default_annotated_trace_path(trace_file: Path, output_json: Optional[Path] = None) -> Path:
+    """Return the default ``*.trace.cachehit.json`` path for *trace_file*."""
+    if output_json is not None:
+        return output_json.expanduser().resolve()
+    if trace_file.name.endswith(".trace.json"):
+        return trace_file.with_name(trace_file.name[: -len(".trace.json")] + ANNOTATED_TRACE_SUFFIX)
+    return trace_file.with_suffix(ANNOTATED_TRACE_SUFFIX)
diff --git a/examples/scaffolding/trace_replay/analysis/streams.py b/examples/scaffolding/trace_replay/analysis/streams.py
new file mode 100644
index 000000000000..03b78bbd54eb
--- /dev/null
+++ b/examples/scaffolding/trace_replay/analysis/streams.py
@@ -0,0 +1,206 @@
+r"""Synthetic token streams + system-prompt registry.
+
+The scaffolding trace records token *counts*, not token IDs. To analyze
+prefix-cache hit rate we synthesize deterministic token IDs:
+
+* :class:`SystemPromptRegistry` shares one token-ID stream per
+  ``system_prompt_id`` UUID — different conversations using the same template
+  see the same IDs (so they hit each other's blocks). Untagged system events
+  fall back to a per-conversation key.
+* :class:`ConversationSegments` mirrors
+  :class:`tensorrt_llm.scaffolding.trace_replay.replay.QueueExecutor`: it stores one token
+  segment per ``message_index`` per ``(branch_path, conversation_id)``, and
+  builds an assistant request's prompt by concatenating those segments.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Mapping, Optional, Sequence, Tuple
+
+
+class TokenIdAllocator:
+    """Hands out fresh, monotonically increasing synthetic token IDs."""
+
+    def __init__(self) -> None:
+        self._next = 0
+
+    def take(self, count: int) -> List[int]:
+        if count <= 0:
+            return []
+        ids = list(range(self._next, self._next + count))
+        self._next += count
+        return ids
+
+
+class SystemPromptRegistry:
+    """Maps a ``system_prompt_id`` UUID to a shared synthetic token sequence.
+
+    Every system event in the trace must carry a non-empty ``system_prompt_id``
+    (validated upstream in :mod:`cache_hit`). Conversations sharing the same
+    UUID see the same token IDs, modeling a real prefix-cache hit; different
+    UUIDs get disjoint streams.
+
+    The registry grows lazily: when a request asks for ``length`` tokens of a
+    UUID and the cached list is shorter, more IDs are appended via the shared
+    :class:`TokenIdAllocator`. Returned slices are stable — a longer
+    subsequent request never invalidates earlier shorter slices.
+    """
+
+    def __init__(self, allocator: TokenIdAllocator) -> None:
+        self._allocator = allocator
+        self._streams: Dict[str, List[int]] = {}
+
+    def tokens(self, system_prompt_id: str, length: int) -> List[int]:
+        if not system_prompt_id:
+            raise ValueError("SystemPromptRegistry requires a non-empty system_prompt_id")
+        stream = self._streams.get(system_prompt_id)
+        if stream is None:
+            stream = []
+            self._streams[system_prompt_id] = stream
+        if len(stream) < length:
+            stream.extend(self._allocator.take(length - len(stream)))
+        return stream[:length]
+
+    def all_streams(self) -> Mapping[str, List[int]]:
+        return self._streams
+
+
+class ConversationSegments:
+    """Per-(branch_path, conversation_id) message-segment store.
+
+    Mirrors :class:`tensorrt_llm.scaffolding.trace_replay.replay.QueueExecutor`: each
+    conversation in each branch holds a list of token-ID segments indexed by
+    ``message_index``. Assistant requests are scored by concatenating these
+    segments to form the prompt. Branch inheritance: when a child branch
+    first touches a conversation, it inherits a snapshot of the closest
+    ancestor branch's segments, so a fork preserves prefix-cache hit
+    potential against the parent.
+    """
+
+    def __init__(
+        self,
+        allocator: TokenIdAllocator,
+        system_registry: SystemPromptRegistry,
+    ) -> None:
+        self._allocator = allocator
+        self._system_registry = system_registry
+        self._segments: Dict[Tuple[Tuple[int, ...], int], List[List[int]]] = {}
+        # First system_prompt_id seen per (branch, conv); used downstream to
+        # group requests by sub-agent / template identity.
+        self._seed_uuids: Dict[Tuple[Tuple[int, ...], int], str] = {}
+
+    def _segments_for(self, branch_path: Sequence[int], conversation_id: int) -> List[List[int]]:
+        key = (tuple(branch_path), conversation_id)
+        existing = self._segments.get(key)
+        if existing is not None:
+            return existing
+
+        # Inherit a snapshot from the closest ancestor branch holding this
+        # conversation. This keeps prefix-cache reuse correct across forks.
+        for parent_len in range(len(branch_path) - 1, -1, -1):
+            parent_key = (tuple(branch_path[:parent_len]), conversation_id)
+            parent = self._segments.get(parent_key)
+            if parent is not None:
+                inherited = [list(seg) for seg in parent]
+                self._segments[key] = inherited
+                return inherited
+
+        new_list: List[List[int]] = []
+        self._segments[key] = new_list
+        return new_list
+
+    def _store(
+        self,
+        branch_path: Sequence[int],
+        conversation_id: int,
+        message_index: Optional[int],
+        token_ids: List[int],
+    ) -> None:
+        segments = self._segments_for(branch_path, conversation_id)
+        if message_index is not None and 0 <= message_index < len(segments):
+            segments[message_index] = token_ids
+        else:
+            segments.append(token_ids)
+
+    def record_system(
+        self,
+        branch_path: Sequence[int],
+        conversation_id: int,
+        message_index: Optional[int],
+        system_prompt_id: str,
+        token_count: int,
+    ) -> None:
+        if not system_prompt_id:
+            raise ValueError(
+                "record_system requires a non-empty system_prompt_id "
+                "(strict mode: every system event must carry a UUID)"
+            )
+        token_ids = list(self._system_registry.tokens(system_prompt_id, token_count))
+        self._store(branch_path, conversation_id, message_index, token_ids)
+        seed_key = (tuple(branch_path), conversation_id)
+        self._seed_uuids.setdefault(seed_key, system_prompt_id)
+
+    def seed_uuid_for(self, branch_path: Sequence[int], conversation_id: int) -> Optional[str]:
+        """Return the first ``system_prompt_id`` seen for this conversation.
+
+        Falls back to the closest ancestor branch's seed (matching the
+        segment-inheritance rule). Returns ``None`` when the conversation
+        never recorded a system event.
+        """
+        path = tuple(branch_path)
+        for parent_len in range(len(path), -1, -1):
+            seed = self._seed_uuids.get((path[:parent_len], conversation_id))
+            if seed is not None:
+                return seed
+        return None
+
+    def record_user_or_tool(
+        self,
+        branch_path: Sequence[int],
+        conversation_id: int,
+        message_index: Optional[int],
+        token_count: int,
+    ) -> None:
+        token_ids = self._allocator.take(token_count)
+        self._store(branch_path, conversation_id, message_index, token_ids)
+
+    def record_assistant_content(
+        self,
+        branch_path: Sequence[int],
+        conversation_id: int,
+        message_index: Optional[int],
+        content_token_count: int,
+    ) -> None:
+        token_ids = self._allocator.take(content_token_count)
+        self._store(branch_path, conversation_id, message_index, token_ids)
+
+    def allocate_tokens(self, count: int) -> List[int]:
+        """Mint fresh, distinct token IDs without storing them in any segment.
+
+        Used to model decode-time KV positions that the real KV cache
+        manager stores in the radix tree but the scaffolding controller
+        does NOT feed back as future-turn content (canonically: reasoning
+        / chain-of-thought tokens). Because the returned IDs are disjoint
+        from every other allocated stream, a later request whose assembled
+        prompt skips this region will diverge from the cached prefix at
+        the block where these tokens were inserted — exactly mirroring
+        what a TRT-LLM C++ KV manager would do.
+        """
+        return self._allocator.take(count)
+
+    def assemble_prompt(
+        self,
+        branch_path: Sequence[int],
+        conversation_id: int,
+    ) -> List[int]:
+        """Return the concatenation of all stored segments for this conv.
+
+        This is what ``tensorrt_llm.scaffolding.trace_replay.replay.QueueExecutor`` sends
+        to the engine as ``prompt=List[int]`` on ``/v1/completions`` — i.e.,
+        the actual ``usage_prompt_tokens`` the engine sees.
+        """
+        segments = self._segments_for(branch_path, conversation_id)
+        prompt: List[int] = []
+        for seg in segments:
+            prompt.extend(seg)
+        return prompt
diff --git a/examples/scaffolding/trace_replay/metrics.py b/examples/scaffolding/trace_replay/metrics.py
new file mode 100644
index 000000000000..66394bbbbf78
--- /dev/null
+++ b/examples/scaffolding/trace_replay/metrics.py
@@ -0,0 +1,295 @@
+from __future__ import annotations
+
+import statistics
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+from tensorrt_llm.scaffolding.trace_replay.execution_trace import ExecutionTrace, TraceEvent
+
+Point3 = Tuple[float, float, Union[int, str]]
+
+
+def count_assistant_completion_tokens(events: List[TraceEvent]) -> int:
+    total = 0
+    for ev in events:
+        if ev.event_type == "message" and ev.role == "assistant":
+            total += ev.completion_tokens or 0
+    return total
+
+
+def count_parallel_regions(events: List[TraceEvent]) -> Dict[str, int]:
+    starts = sum(1 for e in events if e.event_type == "parallel_start")
+    ends = sum(1 for e in events if e.event_type == "parallel_end")
+    return {"parallel_start": starts, "parallel_end": ends}
+
+
+def summarize_trace_events(events: List[TraceEvent]) -> Dict[str, Any]:
+    """Aggregate trace structure for JSON (token budgets, tools, roles)."""
+    event_type_counts: Dict[str, int] = {}
+    role_counts: Dict[str, int] = {}
+    assistant_turns = 0
+    prompt_tokens_assistant_sum = 0
+    completion_tokens_sum = 0
+    reasoning_tokens_sum = 0
+    tool_calls = 0
+    tool_duration_ms_sum = 0.0
+    tool_duration_ms_max = 0.0
+    message_tokens_sum = 0
+    drop_kv = 0
+
+    for ev in events:
+        et = ev.event_type or ""
+        event_type_counts[et] = event_type_counts.get(et, 0) + 1
+        if et == "message" and ev.role:
+            role_counts[ev.role] = role_counts.get(ev.role, 0) + 1
+            if ev.tokens:
+                message_tokens_sum += ev.tokens
+        if et == "message" and ev.role == "assistant":
+            assistant_turns += 1
+            prompt_tokens_assistant_sum += ev.prompt_tokens or 0
+            completion_tokens_sum += ev.completion_tokens or 0
+            reasoning_tokens_sum += ev.reasoning_tokens or 0
+        if et == "tool_call":
+            tool_calls += 1
+            duration_ms = ev.duration_ms or 0.0
+            tool_duration_ms_sum += duration_ms
+            tool_duration_ms_max = max(tool_duration_ms_max, duration_ms)
+        if et == "drop_kv_cache":
+            drop_kv += 1
+
+    return {
+        "event_type_counts": event_type_counts,
+        "message_role_counts": role_counts,
+        "assistant_turns": assistant_turns,
+        "prompt_tokens_assistant_sum": prompt_tokens_assistant_sum,
+        "completion_tokens_sum": completion_tokens_sum,
+        "reasoning_tokens_sum": reasoning_tokens_sum,
+        "non_assistant_message_tokens_sum": message_tokens_sum,
+        "tool_call_count": tool_calls,
+        "tool_call_duration_ms_sum": tool_duration_ms_sum,
+        "tool_call_duration_ms_mean": (tool_duration_ms_sum / tool_calls) if tool_calls else None,
+        "tool_call_duration_ms_max": tool_duration_ms_max,
+        "replay_tool_sleep_wall_s_estimated": tool_duration_ms_sum / 1000.0,
+        "drop_kv_cache_events": drop_kv,
+    }
+
+
+def collect_trace_file_stats(trace_path: Path) -> Dict[str, Any]:
+    st = trace_path.stat()
+    return {
+        "trace_file_name": trace_path.name,
+        "trace_file_size_bytes": st.st_size,
+        "trace_file_mtime_iso": datetime.utcfromtimestamp(st.st_mtime).isoformat() + "Z",
+    }
+
+
+def percentile(data: List[float], q: float) -> float:
+    if not data:
+        raise ValueError("empty data")
+    sorted_values = sorted(data)
+    idx = int(round(q * (len(sorted_values) - 1)))
+    return sorted_values[idx]
+
+
+def compute_replay_run_metrics(
+    *,
+    trace: ExecutionTrace,
+    n_sessions: int,
+    wall_clock_s: float,
+    session_duration_s: List[float],
+    replay_output_token_sum_by_session: List[int],
+    trace_completion_token_sum_by_session: List[int],
+    replay_detail_session0: List[Dict[str, Any]],
+    tensor_parallel_size: int,
+    cuda_device_count: Optional[int] = None,
+) -> Dict[str, Any]:
+    """Compute all replay metrics for one ladder step (or single replay run)."""
+    durations = session_duration_s
+    per_session_replay_output = replay_output_token_sum_by_session
+    per_session_trace_completion = trace_completion_token_sum_by_session
+    total_out_tokens_replay_actual = float(sum(per_session_replay_output))
+    tokens_per_trace_trace_metadata = count_assistant_completion_tokens(trace.events)
+    total_out_tokens_trace_metadata = float(n_sessions * tokens_per_trace_trace_metadata)
+
+    per_session_tp = [
+        per_session_replay_output[i] / durations[i]
+        for i in range(len(durations))
+        if durations[i] > 0
+    ]
+    result: Dict[str, Any] = {
+        "wall_clock_s": wall_clock_s,
+        "assistant_output_tokens_per_trace": tokens_per_trace_trace_metadata,
+        "total_output_tokens_trace_metadata": total_out_tokens_trace_metadata,
+        "total_output_tokens_estimated": total_out_tokens_trace_metadata,
+        "per_session_replay_output_token_sum": per_session_replay_output,
+        "per_session_total_output_tokens": list(per_session_replay_output),
+        "per_session_trace_completion_token_sum": per_session_trace_completion,
+        "assistant_output_tokens_per_trace_replay_actual_mean": (
+            statistics.mean(per_session_replay_output) if per_session_replay_output else None
+        ),
+        "total_output_tokens_replay_actual": total_out_tokens_replay_actual,
+        "replay_assistant_generations_detail_session0": replay_detail_session0,
+        "session_duration_s": durations,
+        "session_duration_min_s": min(durations) if durations else None,
+        "session_duration_max_s": max(durations) if durations else None,
+        "session_duration_sum_s": sum(durations) if durations else None,
+        "session_duration_stdev_s": statistics.stdev(durations) if len(durations) > 1 else 0.0,
+        "session_duration_p50_s": statistics.median(durations) if durations else None,
+        "session_duration_p90_s": percentile(durations, 0.9) if durations else None,
+        "session_duration_p99_s": percentile(durations, 0.99) if durations else None,
+        "session_duration_mean_s": statistics.mean(durations) if durations else None,
+        "session_duration_cv": (statistics.stdev(durations) / statistics.mean(durations))
+        if len(durations) > 1 and statistics.mean(durations) > 0
+        else None,
+        "aggregate_latency_person_s": sum(durations) if durations else None,
+        "median_tps_per_user": statistics.median(per_session_tp) if per_session_tp else None,
+        "mean_tps_per_user": statistics.mean(per_session_tp) if per_session_tp else None,
+        "min_tps_per_user": min(per_session_tp) if per_session_tp else None,
+        "max_tps_per_user": max(per_session_tp) if per_session_tp else None,
+        "output_tps_aggregate": total_out_tokens_replay_actual / wall_clock_s
+        if wall_clock_s > 0
+        else None,
+        "output_tokens_per_wall_s_per_session_mean": (
+            total_out_tokens_replay_actual / wall_clock_s / n_sessions
+        )
+        if wall_clock_s > 0 and n_sessions > 0
+        else None,
+        "mean_tps_per_user_session_time": (total_out_tokens_replay_actual / sum(durations))
+        if durations and sum(durations) > 0
+        else None,
+    }
+    result["output_tps_per_gpu"] = (
+        result["output_tps_aggregate"] / tensor_parallel_size
+        if result["output_tps_aggregate"] is not None and tensor_parallel_size > 0
+        else None
+    )
+    result["pareto_x_median_tps_per_user"] = result.get("median_tps_per_user")
+    result["pareto_y_output_tps_per_gpu"] = result.get("output_tps_per_gpu")
+    result["output_tps_per_aggregate_1gpu_equiv"] = result.get("output_tps_aggregate")
+    if cuda_device_count is not None and cuda_device_count > 0:
+        result["output_tps_per_cuda_device_count"] = (
+            result["output_tps_aggregate"] / cuda_device_count
+            if result["output_tps_aggregate"] is not None
+            else None
+        )
+    return result
+
+
+def _step_from_run(r: Dict[str, Any]) -> Union[int, str]:
+    step = r.get("ladder_step")
+    if step is None:
+        step = r.get("max_batch_size")
+    return step if step is not None else "?"
+
+
+def collect_token_pareto_points(runs: List[Dict[str, Any]]) -> List[Point3]:
+    """Return ``(median_tps_per_user, output_tps_per_gpu, ladder_step)``."""
+    pts: List[Point3] = []
+    for r in runs:
+        if r.get("status") != "success":
+            continue
+        x = r.get("median_tps_per_user")
+        if x is None:
+            x = r.get("pareto_x_median_tps_per_user")
+        y = r.get("output_tps_per_gpu")
+        if y is None:
+            y = r.get("pareto_y_output_tps_per_gpu")
+        if x is None or y is None:
+            continue
+        try:
+            xf, yf = float(x), float(y)
+        except (TypeError, ValueError):
+            continue
+        pts.append((xf, yf, _step_from_run(r)))
+    pts.sort(key=lambda t: t[0])
+    return pts
+
+
+def _gpu_count_for_run(r: Dict[str, Any], data: Dict[str, Any]) -> Optional[int]:
+    """GPU count aligned with ``output_tps_per_gpu`` (aggregate / TP size)."""
+    cfg = r.get("llm_effective_config") or {}
+    tp = cfg.get("tensor_parallel_size")
+    if tp is not None:
+        try:
+            n = int(tp)
+            if n > 0:
+                return n
+        except (TypeError, ValueError):
+            pass
+    cli = data.get("cli_args") or {}
+    tp = cli.get("tensor_parallel_size")
+    if tp is not None:
+        try:
+            n = int(tp)
+            if n > 0:
+                return n
+        except (TypeError, ValueError):
+            pass
+    host = data.get("host") or {}
+    n = host.get("cuda_device_count")
+    if n is not None:
+        try:
+            c = int(n)
+            if c > 0:
+                return c
+        except (TypeError, ValueError):
+            pass
+    return None
+
+
+def _mean_trace_duration_s(r: Dict[str, Any]) -> Optional[float]:
+    """Mean wall time per trace (seconds), from ``session_duration_mean_s`` or sum/n."""
+    mean_s = r.get("session_duration_mean_s")
+    if mean_s is not None:
+        try:
+            mean_value = float(mean_s)
+            if mean_value >= 0:
+                return mean_value
+        except (TypeError, ValueError):
+            pass
+    total_s = r.get("session_duration_sum_s")
+    if total_s is None:
+        total_s = r.get("aggregate_latency_person_s")
+    n = r.get("n_sessions")
+    if total_s is None or n is None:
+        return None
+    try:
+        total_value = float(total_s)
+        sessions = float(n)
+    except (TypeError, ValueError):
+        return None
+    if sessions <= 0:
+        return None
+    return total_value / sessions
+
+
+def collect_agent_pareto_points(
+    runs: List[Dict[str, Any]],
+    data: Dict[str, Any],
+) -> List[Point3]:
+    """Return ``(task/user/h, task/gpu/h, ladder_step)``."""
+    pts: List[Point3] = []
+    for r in runs:
+        if r.get("status") != "success":
+            continue
+        mean_s = _mean_trace_duration_s(r)
+        if mean_s is None or mean_s <= 0:
+            continue
+        x = 3600.0 / mean_s
+        n_raw = r.get("n_sessions")
+        wall = r.get("wall_clock_s")
+        g = _gpu_count_for_run(r, data)
+        if n_raw is None or wall is None or g is None or g <= 0:
+            continue
+        try:
+            n_sessions = float(n_raw)
+            wall_s = float(wall)
+        except (TypeError, ValueError):
+            continue
+        if wall_s <= 0:
+            continue
+        y = n_sessions * 3600.0 / (float(g) * wall_s)
+        pts.append((x, y, _step_from_run(r)))
+    pts.sort(key=lambda t: t[0])
+    return pts
diff --git a/examples/scaffolding/trace_replay/run_trace_replay.py b/examples/scaffolding/trace_replay/run_trace_replay.py
new file mode 100644
index 000000000000..ae4512f4cfd6
--- /dev/null
+++ b/examples/scaffolding/trace_replay/run_trace_replay.py
@@ -0,0 +1,238 @@
+r"""Replay one ``.trace.json`` file via TRTOpenaiWorker and write replay metrics JSON.
+
+Example::
+
+    python examples/scaffolding/trace_replay/run_trace_replay.py \
+        /path/to/some.trace.json \
+        --model your_model_name \
+        --openai-base-url http://127.0.0.1:8000/v1
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import logging
+import os
+import socket
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict
+
+import openai
+
+from tensorrt_llm.scaffolding.trace_replay.execution_trace import ExecutionTrace
+from tensorrt_llm.scaffolding.trace_replay.replay import ReplayEngine, ReplayGenerationStats
+from tensorrt_llm.scaffolding.worker import TRTOpenaiWorker
+
+LOGGER = logging.getLogger(__name__)
+
+try:
+    from .metrics import (
+        collect_trace_file_stats,
+        compute_replay_run_metrics,
+        count_assistant_completion_tokens,
+        count_parallel_regions,
+        summarize_trace_events,
+    )
+except ImportError:
+    from metrics import (  # type: ignore[no-redef]
+        collect_trace_file_stats,
+        compute_replay_run_metrics,
+        count_assistant_completion_tokens,
+        count_parallel_regions,
+        summarize_trace_events,
+    )
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Run one trace replay through TRTOpenaiWorker and save metrics JSON.",
+    )
+    parser.add_argument(
+        "trace_json",
+        type=Path,
+        help="Input .trace.json file.",
+    )
+    parser.add_argument(
+        "--model",
+        type=str,
+        required=True,
+        help="Model name exposed by trtllm-serve OpenAI endpoint.",
+    )
+    parser.add_argument(
+        "--openai-base-url",
+        type=str,
+        default="http://127.0.0.1:8000/v1",
+        help="OpenAI-compatible endpoint base URL for trtllm-serve.",
+    )
+    parser.add_argument(
+        "--openai-api-key",
+        type=str,
+        default=os.environ.get("OPENAI_API_KEY", "EMPTY"),
+        help="OpenAI API key for the endpoint.",
+    )
+    parser.add_argument(
+        "--tensor-parallel-size",
+        type=int,
+        default=1,
+        help="TP size for per-GPU throughput normalization in output metrics.",
+    )
+    parser.add_argument(
+        "--output-json",
+        type=Path,
+        default=None,
+        help="Output JSON path. Default: <trace_base>_<model>_replay_statistics_<timestamp>.json",
+    )
+    return parser.parse_args()
+
+
+def _normalize_base_url(raw: str) -> str:
+    url = raw.strip().rstrip("/")
+    if not url.endswith("/v1"):
+        url = f"{url}/v1"
+    return url
+
+
+def _default_output_json(trace_file: Path, model: str) -> Path:
+    stamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    safe_model = "".join(ch if ch.isalnum() or ch in "._-" else "_" for ch in model).strip("_")
+    safe_model = safe_model or "model"
+    trace_base = (
+        trace_file.name[: -len(".trace.json")]
+        if trace_file.name.endswith(".trace.json")
+        else trace_file.stem
+    )
+    return trace_file.parent / f"{trace_base}_{safe_model}_replay_statistics_{stamp}.json"
+
+
+async def _run_one_replay(
+    worker: TRTOpenaiWorker,
+    trace: ExecutionTrace,
+) -> Dict[str, Any]:
+    stats = ReplayGenerationStats()
+    LOGGER.info("Starting replay for trace_id=%s with %d events", trace.trace_id, len(trace.events))
+    t0 = time.perf_counter()
+    await ReplayEngine(worker, generation_stats=stats).launch_trace(trace)
+    elapsed = time.perf_counter() - t0
+    LOGGER.info("Replay finished in %.3fs", elapsed)
+    return {
+        "elapsed_s": elapsed,
+        "replay_output_token_sum": stats.sum_replay_output_tokens(),
+        "trace_completion_token_sum": stats.sum_trace_completion_tokens(),
+        "per_assistant_generation_detail": stats.entries,
+    }
+
+
+async def _run_replay_with_client(
+    trace: ExecutionTrace,
+    model: str,
+    base_url: str,
+    api_key: str,
+) -> Dict[str, Any]:
+    client = openai.AsyncOpenAI(
+        base_url=base_url,
+        api_key=api_key,
+    )
+    worker = TRTOpenaiWorker(client, model=model)
+    try:
+        return await _run_one_replay(worker, trace)
+    finally:
+        worker.shutdown()
+        await _safe_close_client(client)
+
+
+async def _safe_close_client(client: openai.AsyncOpenAI) -> None:
+    close_fn = getattr(client, "close", None)
+    if callable(close_fn):
+        maybe_coro = close_fn()
+        if asyncio.iscoroutine(maybe_coro):
+            await maybe_coro
+
+
+def main() -> None:
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s - %(message)s",
+    )
+    args = parse_args()
+    trace_file = args.trace_json.expanduser().resolve()
+    if not trace_file.name.endswith(".trace.json"):
+        print(
+            f"error: only .trace.json input is supported, got: {trace_file}",
+            file=sys.stderr,
+        )
+        raise SystemExit(2)
+    output_json = (
+        args.output_json.expanduser().resolve()
+        if args.output_json is not None
+        else _default_output_json(trace_file, args.model).resolve()
+    )
+    output_json.parent.mkdir(parents=True, exist_ok=True)
+
+    LOGGER.info("Loading trace file: %s", trace_file)
+    trace = ExecutionTrace.load(str(trace_file))
+    LOGGER.info("Loaded trace_id=%s, events=%d", trace.trace_id, len(trace.events))
+    base_url = _normalize_base_url(args.openai_base_url)
+    LOGGER.info("Using OpenAI endpoint: %s", base_url)
+    LOGGER.info("Replay model: %s", args.model)
+    replay_result = asyncio.run(
+        _run_replay_with_client(
+            trace=trace,
+            model=args.model,
+            base_url=base_url,
+            api_key=args.openai_api_key,
+        )
+    )
+
+    run_metrics = compute_replay_run_metrics(
+        trace=trace,
+        n_sessions=1,
+        wall_clock_s=float(replay_result["elapsed_s"]),
+        session_duration_s=[float(replay_result["elapsed_s"])],
+        replay_output_token_sum_by_session=[int(replay_result["replay_output_token_sum"])],
+        trace_completion_token_sum_by_session=[int(replay_result["trace_completion_token_sum"])],
+        replay_detail_session0=replay_result["per_assistant_generation_detail"],
+        tensor_parallel_size=args.tensor_parallel_size,
+    )
+
+    record: Dict[str, Any] = {
+        "schema": "trace_replay.single.v1",
+        "run_started_at_utc": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+        "host": {
+            "hostname": socket.gethostname(),
+            "cwd": os.getcwd(),
+            "python_version": sys.version,
+            "pid": os.getpid(),
+        },
+        "cli_argv": sys.argv,
+        "trace_file": str(trace_file),
+        "openai": {
+            "base_url": base_url,
+            "model": args.model,
+            "tensor_parallel_size": args.tensor_parallel_size,
+        },
+        "trace_meta": {
+            "trace_id": trace.trace_id,
+            "num_events": len(trace.events),
+            "parallel_region_counts": count_parallel_regions(trace.events),
+            "assistant_output_tokens_sum": count_assistant_completion_tokens(trace.events),
+            **summarize_trace_events(trace.events),
+            **collect_trace_file_stats(trace_file),
+        },
+        "run": run_metrics,
+        "run_finished_at_utc": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+    }
+
+    with open(output_json, "w", encoding="utf-8") as fp:
+        json.dump(record, fp, indent=2, ensure_ascii=False, default=str)
+
+    LOGGER.info("Replay statistics written to: %s", output_json)
+    print(output_json)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/examples/scaffolding/trace_replay/trace_example/matplotlib__matplotlib-23412/matplotlib__matplotlib-23412.trace.json b/examples/scaffolding/trace_replay/trace_example/matplotlib__matplotlib-23412/matplotlib__matplotlib-23412.trace.json
new file mode 100644
index 000000000000..b072d91ba795
--- /dev/null
+++ b/examples/scaffolding/trace_replay/trace_example/matplotlib__matplotlib-23412/matplotlib__matplotlib-23412.trace.json
@@ -0,0 +1,681 @@
+{
+  "trace_id": "ee41c788-de9a-451c-8d9d-696cdb4b9c2b",
+  "events": [
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "system",
+      "message_index": 0,
+      "system_prompt_id": "c124a9b6-7956-54c2-a145-f5bd02ef527b",
+      "tokens": 2827
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "user",
+      "message_index": 1,
+      "tokens": 1493
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "assistant",
+      "message_index": 2,
+      "tool_calls": [
+        "read_file"
+      ],
+      "prompt_tokens": 4320,
+      "completion_tokens": 176,
+      "reasoning_tokens": 55,
+      "finish_reason": "tool_calls"
+    },
+    {
+      "event_type": "tool_call",
+      "branch_path": [],
+      "tool_call_id": "tooluse_hc5nA1wxYKrOgLaiSo3B5A",
+      "tool_name": "read_file",
+      "duration_ms": 152.79793739318848
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "tool",
+      "message_index": 3,
+      "tokens": 306
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "assistant",
+      "message_index": 4,
+      "tool_calls": [
+        "think"
+      ],
+      "prompt_tokens": 4731,
+      "completion_tokens": 104,
+      "reasoning_tokens": 0,
+      "finish_reason": "tool_calls"
+    },
+    {
+      "event_type": "tool_call",
+      "branch_path": [],
+      "tool_call_id": "tooluse_mpScYcselDkAMVqbXNkcdg",
+      "tool_name": "think",
+      "duration_ms": 2.6912689208984375
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "tool",
+      "message_index": 5,
+      "tokens": 66
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "assistant",
+      "message_index": 6,
+      "tool_calls": [
+        "read_file"
+      ],
+      "prompt_tokens": 4905,
+      "completion_tokens": 99,
+      "reasoning_tokens": 0,
+      "finish_reason": "tool_calls"
+    },
+    {
+      "event_type": "tool_call",
+      "branch_path": [],
+      "tool_call_id": "tooluse_pAtmszVvyeTXTwMUBzCIYv",
+      "tool_name": "read_file",
+      "duration_ms": 19.20604705810547
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "tool",
+      "message_index": 7,
+      "tokens": 476
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "assistant",
+      "message_index": 8,
+      "tool_calls": [
+        "shell"
+      ],
+      "prompt_tokens": 5485,
+      "completion_tokens": 106,
+      "reasoning_tokens": 0,
+      "finish_reason": "tool_calls"
+    },
+    {
+      "event_type": "tool_call",
+      "branch_path": [],
+      "tool_call_id": "tooluse_bORnzoZ8s7WS39sCJmfMXz",
+      "tool_name": "shell",
+      "duration_ms": 35.65192222595215
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "tool",
+      "message_index": 9,
+      "tokens": 247
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "assistant",
+      "message_index": 10,
+      "tool_calls": [
+        "shell"
+      ],
+      "prompt_tokens": 5843,
+      "completion_tokens": 91,
+      "reasoning_tokens": 0,
+      "finish_reason": "tool_calls"
+    },
+    {
+      "event_type": "tool_call",
+      "branch_path": [],
+      "tool_call_id": "tooluse_hx9j1WR3oKRftUDvX2pxPJ",
+      "tool_name": "shell",
+      "duration_ms": 30.002355575561523
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "tool",
+      "message_index": 11,
+      "tokens": 19
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "assistant",
+      "message_index": 12,
+      "tool_calls": [
+        "read_file"
+      ],
+      "prompt_tokens": 5957,
+      "completion_tokens": 99,
+      "reasoning_tokens": 0,
+      "finish_reason": "tool_calls"
+    },
+    {
+      "event_type": "tool_call",
+      "branch_path": [],
+      "tool_call_id": "tooluse_TwX7gJ00JbEVlIn7ZSEYrv",
+      "tool_name": "read_file",
+      "duration_ms": 36.02933883666992
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "tool",
+      "message_index": 13,
+      "tokens": 303
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "assistant",
+      "message_index": 14,
+      "tool_calls": [
+        "shell"
+      ],
+      "prompt_tokens": 6364,
+      "completion_tokens": 401,
+      "reasoning_tokens": 0,
+      "finish_reason": "tool_calls"
+    },
+    {
+      "event_type": "tool_call",
+      "branch_path": [],
+      "tool_call_id": "tooluse_DrSWpulzqx2r9YnxPenWv4",
+      "tool_name": "shell",
+      "duration_ms": 133.87823104858398
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "tool",
+      "message_index": 15,
+      "tokens": 57
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "assistant",
+      "message_index": 16,
+      "tool_calls": [
+        "shell"
+      ],
+      "prompt_tokens": 6826,
+      "completion_tokens": 89,
+      "reasoning_tokens": 0,
+      "finish_reason": "tool_calls"
+    },
+    {
+      "event_type": "tool_call",
+      "branch_path": [],
+      "tool_call_id": "tooluse_P3ULvP14p6MiypN2xOcRIC",
+      "tool_name": "shell",
+      "duration_ms": 39132.69925117493
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "tool",
+      "message_index": 17,
+      "tokens": 299
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "assistant",
+      "message_index": 18,
+      "tool_calls": [
+        "shell"
+      ],
+      "prompt_tokens": 7219,
+      "completion_tokens": 385,
+      "reasoning_tokens": 0,
+      "finish_reason": "tool_calls"
+    },
+    {
+      "event_type": "tool_call",
+      "branch_path": [],
+      "tool_call_id": "tooluse_unGJXVtse7mcbqsOCGOykJ",
+      "tool_name": "shell",
+      "duration_ms": 2209.4762325286865
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "tool",
+      "message_index": 19,
+      "tokens": 103
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "assistant",
+      "message_index": 20,
+      "tool_calls": [
+        "think"
+      ],
+      "prompt_tokens": 7712,
+      "completion_tokens": 76,
+      "reasoning_tokens": 0,
+      "finish_reason": "tool_calls"
+    },
+    {
+      "event_type": "tool_call",
+      "branch_path": [],
+      "tool_call_id": "tooluse_8lXa8Cq63Bh82TkchnMYor",
+      "tool_name": "think",
+      "duration_ms": 3.214597702026367
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "tool",
+      "message_index": 21,
+      "tokens": 38
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "assistant",
+      "message_index": 22,
+      "tool_calls": [
+        "shell"
+      ],
+      "prompt_tokens": 7830,
+      "completion_tokens": 391,
+      "reasoning_tokens": 0,
+      "finish_reason": "tool_calls"
+    },
+    {
+      "event_type": "tool_call",
+      "branch_path": [],
+      "tool_call_id": "tooluse_3QlpkUPLUuXAqk0PlSu1wN",
+      "tool_name": "shell",
+      "duration_ms": 467.3750400543213
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "tool",
+      "message_index": 23,
+      "tokens": 708
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "assistant",
+      "message_index": 24,
+      "tool_calls": [
+        "think"
+      ],
+      "prompt_tokens": 8934,
+      "completion_tokens": 106,
+      "reasoning_tokens": 0,
+      "finish_reason": "tool_calls"
+    },
+    {
+      "event_type": "tool_call",
+      "branch_path": [],
+      "tool_call_id": "tooluse_lmSEbgT05vGtRU2PEdaLkA",
+      "tool_name": "think",
+      "duration_ms": 6.128787994384766
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "tool",
+      "message_index": 25,
+      "tokens": 68
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "assistant",
+      "message_index": 26,
+      "tool_calls": [
+        "shell"
+      ],
+      "prompt_tokens": 9112,
+      "completion_tokens": 376,
+      "reasoning_tokens": 0,
+      "finish_reason": "tool_calls"
+    },
+    {
+      "event_type": "tool_call",
+      "branch_path": [],
+      "tool_call_id": "tooluse_7wBkysPI7tbruZolMAztbJ",
+      "tool_name": "shell",
+      "duration_ms": 514.0607357025146
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "tool",
+      "message_index": 27,
+      "tokens": 67
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "assistant",
+      "message_index": 28,
+      "tool_calls": [
+        "shell"
+      ],
+      "prompt_tokens": 9560,
+      "completion_tokens": 117,
+      "reasoning_tokens": 0,
+      "finish_reason": "tool_calls"
+    },
+    {
+      "event_type": "tool_call",
+      "branch_path": [],
+      "tool_call_id": "tooluse_SmWVJn7jNN6UVTR2DEvbFN",
+      "tool_name": "shell",
+      "duration_ms": 35.076141357421875
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "tool",
+      "message_index": 29,
+      "tokens": 26
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "assistant",
+      "message_index": 30,
+      "tool_calls": [
+        "shell"
+      ],
+      "prompt_tokens": 9707,
+      "completion_tokens": 87,
+      "reasoning_tokens": 0,
+      "finish_reason": "tool_calls"
+    },
+    {
+      "event_type": "tool_call",
+      "branch_path": [],
+      "tool_call_id": "tooluse_SEtRKX30Pi6WI0NpvoXm3n",
+      "tool_name": "shell",
+      "duration_ms": 2129.9984455108643
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "tool",
+      "message_index": 31,
+      "tokens": 132
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "assistant",
+      "message_index": 32,
+      "tool_calls": [
+        "shell"
+      ],
+      "prompt_tokens": 9931,
+      "completion_tokens": 103,
+      "reasoning_tokens": 0,
+      "finish_reason": "tool_calls"
+    },
+    {
+      "event_type": "tool_call",
+      "branch_path": [],
+      "tool_call_id": "tooluse_ghses6qZQmTpCdE8o8MaBQ",
+      "tool_name": "shell",
+      "duration_ms": 613.4977340698242
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "tool",
+      "message_index": 33,
+      "tokens": 521
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "assistant",
+      "message_index": 34,
+      "tool_calls": [
+        "think"
+      ],
+      "prompt_tokens": 10560,
+      "completion_tokens": 86,
+      "reasoning_tokens": 0,
+      "finish_reason": "tool_calls"
+    },
+    {
+      "event_type": "tool_call",
+      "branch_path": [],
+      "tool_call_id": "tooluse_zAucvesKFSyp4eoBc8KJQG",
+      "tool_name": "think",
+      "duration_ms": 2.9976367950439453
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "tool",
+      "message_index": 35,
+      "tokens": 48
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "assistant",
+      "message_index": 36,
+      "tool_calls": [
+        "grep_files"
+      ],
+      "prompt_tokens": 10698,
+      "completion_tokens": 88,
+      "reasoning_tokens": 0,
+      "finish_reason": "tool_calls"
+    },
+    {
+      "event_type": "tool_call",
+      "branch_path": [],
+      "tool_call_id": "tooluse_cU6A17b6ItcH8YkDUeEYhN",
+      "tool_name": "grep_files",
+      "duration_ms": 82.65852928161621
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "tool",
+      "message_index": 37,
+      "tokens": 14
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "assistant",
+      "message_index": 38,
+      "tool_calls": [
+        "shell"
+      ],
+      "prompt_tokens": 10804,
+      "completion_tokens": 113,
+      "reasoning_tokens": 0,
+      "finish_reason": "tool_calls"
+    },
+    {
+      "event_type": "tool_call",
+      "branch_path": [],
+      "tool_call_id": "tooluse_cu4zWocZo2psKaJNiX8FCc",
+      "tool_name": "shell",
+      "duration_ms": 1683.6841106414795
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "tool",
+      "message_index": 39,
+      "tokens": 309
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "assistant",
+      "message_index": 40,
+      "tool_calls": [
+        "shell"
+      ],
+      "prompt_tokens": 11231,
+      "completion_tokens": 112,
+      "reasoning_tokens": 0,
+      "finish_reason": "tool_calls"
+    },
+    {
+      "event_type": "tool_call",
+      "branch_path": [],
+      "tool_call_id": "tooluse_zKJUWJf0wp6cHmkc6hiQwg",
+      "tool_name": "shell",
+      "duration_ms": 25.85768699645996
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "tool",
+      "message_index": 41,
+      "tokens": 246
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "assistant",
+      "message_index": 42,
+      "tool_calls": [
+        "grep_files"
+      ],
+      "prompt_tokens": 11594,
+      "completion_tokens": 126,
+      "reasoning_tokens": 0,
+      "finish_reason": "tool_calls"
+    },
+    {
+      "event_type": "tool_call",
+      "branch_path": [],
+      "tool_call_id": "tooluse_eMO0fFvBmepNZ4ER88nbHB",
+      "tool_name": "grep_files",
+      "duration_ms": 15.046119689941406
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "tool",
+      "message_index": 43,
+      "tokens": 14
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "assistant",
+      "message_index": 44,
+      "tool_calls": [
+        "shell"
+      ],
+      "prompt_tokens": 11738,
+      "completion_tokens": 73,
+      "reasoning_tokens": 0,
+      "finish_reason": "tool_calls"
+    },
+    {
+      "event_type": "tool_call",
+      "branch_path": [],
+      "tool_call_id": "tooluse_ecJvEvHv4JHSateYtBXYuj",
+      "tool_name": "shell",
+      "duration_ms": 18.251419067382812
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "tool",
+      "message_index": 45,
+      "tokens": 69
+    },
+    {
+      "event_type": "message",
+      "branch_path": [],
+      "conversation_id": 0,
+      "role": "assistant",
+      "message_index": 46,
+      "tool_calls": [
+        "complete_task"
+      ],
+      "prompt_tokens": 11884,
+      "completion_tokens": 412,
+      "reasoning_tokens": 0,
+      "finish_reason": "tool_calls"
+    },
+    {
+      "event_type": "tool_call",
+      "branch_path": [],
+      "tool_call_id": "tooluse_DaiJo1mPdg8iN2wZ8b3laM",
+      "tool_name": "complete_task",
+      "duration_ms": 3.222227096557617
+    }
+  ]
+}
diff --git a/tensorrt_llm/scaffolding/__init__.py b/tensorrt_llm/scaffolding/__init__.py
index 98053bb829e0..d06d5f3b7394 100644
--- a/tensorrt_llm/scaffolding/__init__.py
+++ b/tensorrt_llm/scaffolding/__init__.py
@@ -4,23 +4,32 @@
                          MajorityVoteController, NativeChatController,
                          NativeGenerationController, NativeRewardController,
                          ParallelProcess, PRMController)
+from .execution_scope import ExecutionScope, current_scope
 from .math_utils import (extract_answer_from_boxed, extract_answer_with_regex,
                          get_digit_majority_vote_result)
 from .scaffolding_llm import ScaffoldingLlm
 from .task import (AssistantMessage, ChatTask, DropKVCacheTask, GenerationTask,
                    MCPCallTask, OpenAIToolDescription, RewardTask,
                    StreamGenerationTask, SystemMessage, Task, TaskStatus,
-                   UserMessage)
+                   TokenizeTask, UserMessage)
 from .task_collection import (ChatTokenCounter, DropKVCacheWorkerTag,
-                              GenerationTokenCounter, QueryCollector,
-                              TaskCollection, TaskMetricsCollector, TaskTimer,
-                              drop_kv_cache_scope, sub_request_node,
-                              with_task_collection)
-from .worker import (MCPWorker, OpenaiWorker, TRTLLMWorker, TRTOpenaiWorker,
-                     Worker)
+                              ExecutionTracer, GenerationTokenCounter,
+                              QueryCollector, TaskCollection,
+                              TaskMetricsCollector, TaskTimer,
+                              TokenizeWorkerTag, drop_kv_cache_scope,
+                              sub_request_node, tokenize_trace_scope,
+                              with_execution_tracing, with_task_collection)
+from .trace_replay.execution_trace import ExecutionTrace, TraceEvent
+from .trace_replay.replay import (QueueExecutor, QueueManager, ReplayEngine,
+                                  ReplayGenerationStats)
+from .utils import system_prompt
+from .worker import (ApiaryMCPWorker, MCPWorker, OpenaiWorker, TRTLLMWorker,
+                     TRTOpenaiWorker, Worker)
 
 __all__ = [
     "ScaffoldingLlm",
+    "ExecutionScope",
+    "current_scope",
     "ParallelProcess",
     "Controller",
     "NativeChatController",
@@ -47,6 +56,7 @@
     "TRTOpenaiWorker",
     "TRTLLMWorker",
     "MCPWorker",
+    "ApiaryMCPWorker",
     "TaskStatus",
     "extract_answer_from_boxed",
     "extract_answer_with_regex",
@@ -58,10 +68,21 @@
     "TaskTimer",
     "QueryCollector",
     "TaskMetricsCollector",
-    "DetailedTaskProfiler",
     "sub_request_node",
     "async_scaffolding_benchmark",
     "ScaffoldingBenchRequest",
     "DropKVCacheWorkerTag",
     "drop_kv_cache_scope",
+    "TokenizeTask",
+    "TokenizeWorkerTag",
+    "tokenize_trace_scope",
+    "ExecutionTrace",
+    "TraceEvent",
+    "ExecutionTracer",
+    "with_execution_tracing",
+    "QueueExecutor",
+    "QueueManager",
+    "ReplayEngine",
+    "ReplayGenerationStats",
+    "system_prompt",
 ]
diff --git a/tensorrt_llm/scaffolding/benchmark.py b/tensorrt_llm/scaffolding/benchmark.py
index 740d725428e3..99821de2b7ad 100644
--- a/tensorrt_llm/scaffolding/benchmark.py
+++ b/tensorrt_llm/scaffolding/benchmark.py
@@ -14,6 +14,27 @@
 
 class ScaffoldingBenchRequest(BaseModel):
     prompt: str
+    scope_params: dict[str, str | list[str]] | None = None
+
+
+def _apply_scope_params(
+    scaffolding_llm: ScaffoldingLlm,
+    request: ScaffoldingBenchRequest,
+    result: ScaffoldingResult,
+) -> None:
+    if request.scope_params is None:
+        return
+
+    seen_workers: set[int] = set()
+    for worker in scaffolding_llm.workers.values():
+        worker_id = id(worker)
+        if worker_id in seen_workers:
+            continue
+        seen_workers.add(worker_id)
+
+        setter = getattr(worker, "set_scope_params", None)
+        if callable(setter):
+            setter(result.id, **request.scope_params)
 
 
 async def enqueue_requests(input_queue, requests):
@@ -32,6 +53,7 @@ async def process_request(scaffolding_llm: ScaffoldingLlm, request,
 
         request_start_time = time.time()
         result = scaffolding_llm.generate_async(request.prompt)
+        _apply_scope_params(scaffolding_llm, request, result)
         await result.aresult()
         request_execution_time = time.time() - request_start_time
         await output_queue.put(
diff --git a/tensorrt_llm/scaffolding/contrib/Coder/__init__.py b/tensorrt_llm/scaffolding/contrib/Coder/__init__.py
new file mode 100644
index 000000000000..356b0890cf50
--- /dev/null
+++ b/tensorrt_llm/scaffolding/contrib/Coder/__init__.py
@@ -0,0 +1,83 @@
+"""Coder agent for the Scaffolding framework.
+
+This module provides a coding agent that can read, write, and modify code
+using the TensorRT-LLM Scaffolding framework.  Tool execution is backed by
+the Coder Apiary MCP server (``coder_apiary_mcp.py``), which runs each
+agent request in an isolated Apiary sandbox.
+
+Example usage:
+    ```python
+    from tensorrt_llm.scaffolding.worker import TRTOpenaiWorker, ApiaryMCPWorker
+    from tensorrt_llm.scaffolding.contrib.Coder import create_coder_scaffolding_llm
+
+    # Create workers
+    generation_worker = TRTOpenaiWorker(
+        base_url="http://localhost:8000/v1",
+        api_key="your-api-key",
+        model="your-model",
+    )
+
+    # Start CoderMCP server first:
+    # python examples/scaffolding/mcp/coder/coder_mcp.py --port 8083
+
+    mcp_worker = ApiaryMCPWorker("http://localhost:8083/sse")
+
+    # Create the Coder agent
+    coder = create_coder_scaffolding_llm(
+        generation_worker=generation_worker,
+        mcp_worker=mcp_worker,
+    )
+
+    # Run a coding task
+    result = coder.generate("Add error handling to the parse_config function")
+    print(result.text)
+    ```
+"""
+
+from .coder import (
+    Coder,
+    CoderTask,
+    SWEBenchCoder,
+    create_coder_scaffolding_llm,
+    create_swebench_coder_scaffolding_llm,
+)
+from .prompts import SWEBENCH_SYSTEM_PROMPT
+from .tools import (
+    ALL_CODER_TOOLS,
+    FILE_TOOLS,
+    PLANNING_TOOLS,
+    SHELL_TOOLS,
+    complete_task_tool,
+    exec_tool,
+    grep_files_tool,
+    list_dir_tool,
+    read_file_tool,
+    shell_tool,
+    think_tool,
+    update_plan_tool,
+)
+
+__all__ = [
+    # Main controller
+    "Coder",
+    "CoderTask",
+    # Factory function
+    "create_coder_scaffolding_llm",
+    # SWE-bench
+    "SWEBenchCoder",
+    "SWEBENCH_SYSTEM_PROMPT",
+    "create_swebench_coder_scaffolding_llm",
+    # Tool definitions
+    "ALL_CODER_TOOLS",
+    "FILE_TOOLS",
+    "SHELL_TOOLS",
+    "PLANNING_TOOLS",
+    "read_file_tool",
+    "list_dir_tool",
+    "grep_files_tool",
+    "update_plan_tool",
+    "exec_tool",
+    "shell_tool",
+    "think_tool",
+    "complete_task_tool",
+]
diff --git a/tensorrt_llm/scaffolding/contrib/Coder/coder.py b/tensorrt_llm/scaffolding/contrib/Coder/coder.py
new file mode 100644
index 000000000000..a89c621be882
--- /dev/null
+++ b/tensorrt_llm/scaffolding/contrib/Coder/coder.py
@@ -0,0 +1,314 @@
+"""Coder agent supervisor and factory functions for the Scaffolding framework.
+
+This module implements a coding agent that can read, write, and modify code
+using MCP-based tool execution for file system operations and shell commands.
+It also hosts the SWE-bench variant (:class:`SWEBenchCoder`), which shares all
+orchestration with :class:`Coder` and only differs in its system prompt and how
+the final result is post-processed.
+"""
+
+from dataclasses import dataclass, field
+from typing import List
+
+from tensorrt_llm.scaffolding.controller import (
+    ChatWithMCPController,
+    Controller,
+    NativeGenerationController,
+)
+from tensorrt_llm.scaffolding.scaffolding_llm import ScaffoldingLlm
+from tensorrt_llm.scaffolding.task import ChatTask, MCPCallTask, SystemMessage, Task
+from tensorrt_llm.scaffolding.task_collection import (
+    DropKVCacheWorkerTag,
+    TaskMetricsCollector,
+    TokenizeWorkerTag,
+    drop_kv_cache_scope,
+    sub_request_node,
+    tokenize_trace_scope,
+    with_execution_tracing,
+    with_task_collection,
+)
+from tensorrt_llm.scaffolding.worker import Worker
+
+from .prompts import CODER_SYSTEM_PROMPT, SWEBENCH_SYSTEM_PROMPT
+from .swebench_utils import extract_swebench_complete_task_for_preds
+from .tools import ALL_CODER_TOOLS
+
+
+@dataclass
+class CoderTask(Task):
+    """Task for the Coder agent."""
+
+    user_prompt: str = field(default=None)
+    final_response: str = field(default=None)
+
+    @staticmethod
+    def create_from_prompt(prompt: str) -> "CoderTask":
+        """Create a CoderTask from a user prompt."""
+        task = CoderTask()
+        task.user_prompt = prompt
+        task.input_str = prompt
+        return task
+
+
+class _BaseCoderController(Controller):
+    """Shared logic for the Coder controllers.
+
+    Subclasses set :attr:`SYSTEM_PROMPT` and may override :meth:`_user_prompt`
+    (how the user text is read off the task) and :meth:`_finalize` (how the
+    final result is written back). The tool-calling loop itself is identical:
+    build a :class:`ChatTask` with the system prompt and tools, delegate to the
+    ``chat_with_tools_controller``, then record the last assistant message.
+    """
+
+    tools = ALL_CODER_TOOLS
+    SYSTEM_PROMPT: str = None
+
+    def __init__(self, chat_with_tools_controller: Controller):
+        """Initialize the controller.
+
+        Args:
+            chat_with_tools_controller: Controller for chat with tool calling
+                                        (typically ChatWithMCPController).
+        """
+        super().__init__()
+        self.chat_with_tools_controller = chat_with_tools_controller
+
+    def clone(self):
+        """Create a copy of this controller for parallel execution.
+
+        Each clone runs in its own :class:`ExecutionScope` (assigned
+        automatically by :class:`ScaffoldingLlm` when entering a
+        ``ParallelProcess`` branch), so ``ApiaryMCPWorker`` routes its
+        tool calls to a dedicated SSE connection without manual wiring.
+        """
+        cloned_ctrl = self.chat_with_tools_controller.clone()
+        return type(self)(chat_with_tools_controller=cloned_ctrl)
+
+    def process(self, tasks: List[Task], **kwargs):
+        """Run the tool-calling loop for a single task."""
+        task = tasks[0]
+
+        chat_task = ChatTask.create_from_prompt(
+            self._user_prompt(task),
+            [SystemMessage(content=self.SYSTEM_PROMPT)],
+            tools=self.tools,
+        )
+
+        # Delegate to chat_with_tools_controller for the tool-calling loop.
+        yield from self.chat_with_tools_controller.process([chat_task])
+
+        task.output_str = chat_task.last_assistant_content()
+        self._finalize(task, chat_task)
+        return
+
+    def _user_prompt(self, task: Task) -> str:
+        """Read the user prompt from the task (override as needed)."""
+        return task.input_str
+
+    def _finalize(self, task: Task, chat_task: ChatTask) -> None:
+        """Hook to post-process the finished chat (override as needed)."""
+
+
+@sub_request_node("agent_coder", is_top_level=True)
+@drop_kv_cache_scope()
+class Coder(_BaseCoderController):
+    """Coding agent controller that handles tool calling and code modifications.
+
+    Receives a user prompt, runs the tool-calling loop via
+    :class:`ChatWithMCPController`, and returns the final assistant response.
+    """
+
+    SYSTEM_PROMPT = CODER_SYSTEM_PROMPT
+
+    def _user_prompt(self, task: Task) -> str:
+        if isinstance(task, CoderTask):
+            return task.user_prompt
+        return task.input_str
+
+    def _finalize(self, task: Task, chat_task: ChatTask) -> None:
+        if isinstance(task, CoderTask):
+            task.final_response = task.output_str
+
+
+@sub_request_node("agent_swebench_coder", is_top_level=True)
+# @drop_kv_cache_scope()
+class SWEBenchCoder(_BaseCoderController):
+    """SWE-bench variant of the Coder controller.
+
+    Uses :data:`SWEBENCH_SYSTEM_PROMPT` instead of the generic Coder prompt and
+    extracts the ``preds.json`` patch/summary from the final ``complete_task``
+    tool call.
+    """
+
+    SYSTEM_PROMPT = SWEBENCH_SYSTEM_PROMPT
+
+    def _finalize(self, task: Task, chat_task: ChatTask) -> None:
+        complete_task_result = extract_swebench_complete_task_for_preds(chat_task)
+        task.customized_result_fields["swebench_model_patch"] = complete_task_result["model_patch"]
+        task.customized_result_fields["swebench_summary"] = complete_task_result["summary"]
+
+
+def _wrap_with_detailed_profiler(controller_type, controller_name):
+    """Attach a :class:`TaskMetricsCollector` to a controller class."""
+    return with_task_collection(
+        f"{controller_name}TaskCollection",
+        TaskMetricsCollector,
+        controller_name=controller_name,
+        task_types=[ChatTask, MCPCallTask],
+        enable_print=True,
+        capture_messages=True,
+    )(controller_type)
+
+
+def _build_coder_scaffolding_llm(
+    *,
+    coder_type: type,
+    coder_name: str,
+    generation_worker: Worker,
+    mcp_worker: Worker,
+    max_tokens: int,
+    max_iterations: int,
+    max_parallel_requests: int,
+    enable_statistics: bool,
+    enable_tracing: bool,
+) -> ScaffoldingLlm:
+    """Assemble a :class:`ScaffoldingLlm` for a Coder-family controller.
+
+    Shared by :func:`create_coder_scaffolding_llm` and
+    :func:`create_swebench_coder_scaffolding_llm`; ``coder_type`` and
+    ``coder_name`` are the only things that differ between them.
+    """
+    sampling_params = {
+        "temperature": 0.7,
+        "max_tokens": max_tokens,
+    }
+
+    generation_controller = NativeGenerationController(sampling_params=sampling_params)
+
+    chat_with_mcp_controller_type = ChatWithMCPController
+    if enable_statistics:
+        chat_with_mcp_controller_type = _wrap_with_detailed_profiler(
+            ChatWithMCPController, "ChatWithMCP"
+        )
+        coder_type = _wrap_with_detailed_profiler(coder_type, coder_name)
+
+    if enable_tracing:
+        coder_type = with_execution_tracing(coder_name)(coder_type)
+        coder_type = tokenize_trace_scope()(coder_type)
+
+    chat_with_tools_controller = chat_with_mcp_controller_type(
+        generation_controller, max_iterations=max_iterations
+    )
+
+    coder_controller = coder_type(
+        chat_with_tools_controller=chat_with_tools_controller,
+    )
+
+    workers = {
+        NativeGenerationController.WorkerTag.GENERATION: generation_worker,
+        ChatWithMCPController.WorkerTag.TOOLCALL: mcp_worker,
+        DropKVCacheWorkerTag.DROP_KV_CACHE: generation_worker,
+    }
+    if enable_tracing:
+        workers[TokenizeWorkerTag.TOKENIZE] = generation_worker
+
+    scaffolding_llm = ScaffoldingLlm(
+        coder_controller,
+        workers,
+        max_parallel_requests=max_parallel_requests,
+    )
+
+    if enable_tracing:
+        scaffolding_llm.enable_output_task_collection()
+
+    return scaffolding_llm
+
+
+def create_coder_scaffolding_llm(
+    generation_worker: Worker,
+    mcp_worker: Worker,
+    max_tokens: int = 131072,
+    max_iterations: int = 50,
+    max_parallel_requests: int = 16,
+    enable_statistics: bool = False,
+    enable_tracing: bool = False,
+) -> ScaffoldingLlm:
+    """Create a ScaffoldingLlm configured for the Coder agent.
+
+    Args:
+        generation_worker: Worker for LLM generation (e.g., TRTOpenaiWorker).
+        mcp_worker: Worker for MCP tool calls (e.g., MCPWorker connected to CoderMCP server).
+        max_tokens: Maximum tokens for generation.
+        max_iterations: Maximum tool-calling iterations.
+        max_parallel_requests: Maximum parallel requests to process.
+        enable_statistics: Enable detailed profiling/metrics.
+
+    Returns:
+        Configured ScaffoldingLlm instance.
+
+    Example:
+        ```python
+        from tensorrt_llm.scaffolding.worker import TRTOpenaiWorker, ApiaryMCPWorker
+        from tensorrt_llm.scaffolding.contrib.Coder import create_coder_scaffolding_llm
+
+        # Create workers
+        generation_worker = TRTOpenaiWorker(
+            base_url="http://localhost:8000/v1",
+            api_key="your-api-key",
+            model="your-model",
+        )
+
+        # Start CoderMCP server first:
+        # python examples/scaffolding/mcp/coder/coder_mcp.py --port 8083
+
+        mcp_worker = ApiaryMCPWorker("http://localhost:8083/sse")
+
+        # Create the Coder agent
+        coder = create_coder_scaffolding_llm(
+            generation_worker=generation_worker,
+            mcp_worker=mcp_worker,
+        )
+
+        # Run a coding task
+        result = coder.generate("Add a hello world function to main.py")
+        print(result.text)
+        ```
+    """
+    return _build_coder_scaffolding_llm(
+        coder_type=Coder,
+        coder_name="Coder",
+        generation_worker=generation_worker,
+        mcp_worker=mcp_worker,
+        max_tokens=max_tokens,
+        max_iterations=max_iterations,
+        max_parallel_requests=max_parallel_requests,
+        enable_statistics=enable_statistics,
+        enable_tracing=enable_tracing,
+    )
+
+
+def create_swebench_coder_scaffolding_llm(
+    generation_worker: Worker,
+    mcp_worker: Worker,
+    max_tokens: int = 131072,
+    max_iterations: int = 100,
+    max_parallel_requests: int = 16,
+    enable_statistics: bool = False,
+    enable_tracing: bool = False,
+) -> ScaffoldingLlm:
+    """Create a :class:`ScaffoldingLlm` configured for SWE-bench evaluation.
+
+    Mirrors :func:`create_coder_scaffolding_llm` but uses
+    :class:`SWEBenchCoder` with the SWE-bench-specific system prompt.
+    """
+    return _build_coder_scaffolding_llm(
+        coder_type=SWEBenchCoder,
+        coder_name="SWEBenchCoder",
+        generation_worker=generation_worker,
+        mcp_worker=mcp_worker,
+        max_tokens=max_tokens,
+        max_iterations=max_iterations,
+        max_parallel_requests=max_parallel_requests,
+        enable_statistics=enable_statistics,
+        enable_tracing=enable_tracing,
+    )
diff --git a/tensorrt_llm/scaffolding/contrib/Coder/prompts.py b/tensorrt_llm/scaffolding/contrib/Coder/prompts.py
new file mode 100644
index 000000000000..a4a2706294e3
--- /dev/null
+++ b/tensorrt_llm/scaffolding/contrib/Coder/prompts.py
@@ -0,0 +1,350 @@
+# ruff: noqa: E501
+
+from tensorrt_llm.scaffolding import system_prompt
+
+CODER_SYSTEM_PROMPT = system_prompt(
+    """You are GPT-5.2 running in the Codex CLI, a terminal-based coding assistant. Codex CLI is an open source project led by OpenAI. You are expected to be precise, safe, and helpful.
+
+Your capabilities:
+
+- Receive user prompts and other context provided by the harness, such as files in the workspace.
+- Communicate with the user by streaming thinking & responses, and by making & updating plans.
+- Emit function calls to run terminal commands (including file edits via ``sed``, ``tee``, heredocs, etc.). Depending on how this specific run is configured, you can request that these function calls be escalated to the user for approval before running. More on this in the "Sandbox and approvals" section.
+
+Within this context, Codex refers to the open-source agentic coding interface (not the old Codex language model built by OpenAI).
+
+# How you work
+
+## Personality
+
+Your default personality and tone is concise, direct, and friendly. You communicate efficiently, always keeping the user clearly informed about ongoing actions without unnecessary detail. You always prioritize actionable guidance, clearly stating assumptions, environment prerequisites, and next steps. Unless explicitly asked, you avoid excessively verbose explanations about your work.
+
+## AGENTS.md spec
+- Repos often contain AGENTS.md files. These files can appear anywhere within the repository.
+- These files are a way for humans to give you (the agent) instructions or tips for working within the container.
+- Some examples might be: coding conventions, info about how code is organized, or instructions for how to run or test code.
+- Instructions in AGENTS.md files:
+    - The scope of an AGENTS.md file is the entire directory tree rooted at the folder that contains it.
+    - For every file you touch in the final patch, you must obey instructions in any AGENTS.md file whose scope includes that file.
+    - Instructions about code style, structure, naming, etc. apply only to code within the AGENTS.md file's scope, unless the file states otherwise.
+    - More-deeply-nested AGENTS.md files take precedence in the case of conflicting instructions.
+    - Direct system/developer/user instructions (as part of a prompt) take precedence over AGENTS.md instructions.
+- The contents of the AGENTS.md file at the root of the repo and any directories from the CWD up to the root are included with the developer message and don't need to be re-read. When working in a subdirectory of CWD, or a directory outside the CWD, check for any AGENTS.md files that may be applicable.
+
+## Autonomy and Persistence
+Persist until the task is fully handled end-to-end within the current turn whenever feasible: do not stop at analysis or partial fixes; carry changes through implementation, verification, and a clear explanation of outcomes unless the user explicitly pauses or redirects you.
+
+Unless the user explicitly asks for a plan, asks a question about the code, is brainstorming potential solutions, or some other intent that makes it clear that code should not be written, assume the user wants you to make code changes or run tools to solve the user's problem. In these cases, it's bad to output your proposed solution in a message, you should go ahead and actually implement the change. If you encounter challenges or blockers, you should attempt to resolve them yourself.
+
+## Responsiveness
+
+## Planning
+
+You have access to an `update_plan` tool which tracks steps and progress and renders them to the user. Using the tool helps demonstrate that you've understood the task and convey how you're approaching it. Plans can help to make complex, ambiguous, or multi-phase work clearer and more collaborative for the user. A good plan should break the task into meaningful, logically ordered steps that are easy to verify as you go.
+
+Note that plans are not for padding out simple work with filler steps or stating the obvious. The content of your plan should not involve doing anything that you aren't capable of doing (i.e. don't try to test things that you can't test). Do not use plans for simple or single-step queries that you can just do or answer immediately.
+
+Do not repeat the full contents of the plan after an `update_plan` call — the harness already displays it. Instead, summarize the change made and highlight any important context or next step.
+
+Before running a command, consider whether or not you have completed the previous step, and make sure to mark it as completed before moving on to the next step. It may be the case that you complete all steps in your plan after a single pass of implementation. If this is the case, you can simply mark all the planned steps as completed. Sometimes, you may need to change plans in the middle of a task: call `update_plan` with the updated plan and make sure to provide an `explanation` of the rationale when doing so.
+
+Maintain statuses in the tool: exactly one item in_progress at a time; mark items complete when done; post timely status transitions. Do not jump an item from pending to completed: always set it to in_progress first. Do not batch-complete multiple items after the fact. Finish with all items completed or explicitly canceled/deferred before ending the turn. Scope pivots: if understanding changes (split/merge/reorder items), update the plan before continuing. Do not let the plan go stale while coding.
+
+Use a plan when:
+
+- The task is non-trivial and will require multiple actions over a long time horizon.
+- There are logical phases or dependencies where sequencing matters.
+- The work has ambiguity that benefits from outlining high-level goals.
+- You want intermediate checkpoints for feedback and validation.
+- When the user asked you to do more than one thing in a single prompt
+- The user has asked you to use the plan tool (aka "TODOs")
+- You generate additional steps while working, and plan to do them before yielding to the user
+
+### Examples
+
+**High-quality plans**
+
+Example 1:
+
+1. Add CLI entry with file args
+2. Parse Markdown via CommonMark library
+3. Apply semantic HTML template
+4. Handle code blocks, images, links
+5. Add error handling for invalid files
+
+Example 2:
+
+1. Define CSS variables for colors
+2. Add toggle with localStorage state
+3. Refactor components to use variables
+4. Verify all views for readability
+5. Add smooth theme-change transition
+
+Example 3:
+
+1. Set up Node.js + WebSocket server
+2. Add join/leave broadcast events
+3. Implement messaging with timestamps
+4. Add usernames + mention highlighting
+5. Persist messages in lightweight DB
+6. Add typing indicators + unread count
+
+**Low-quality plans**
+
+Example 1:
+
+1. Create CLI tool
+2. Add Markdown parser
+3. Convert to HTML
+
+Example 2:
+
+1. Add dark mode toggle
+2. Save preference
+3. Make styles look good
+
+Example 3:
+
+1. Create single-file HTML game
+2. Run quick sanity check
+3. Summarize usage instructions
+
+If you need to write a plan, only write high quality plans, not low quality ones.
+
+## Task execution
+
+You are a coding agent. You must keep going until the query or task is completely resolved, before ending your turn and yielding back to the user. Persist until the task is fully handled end-to-end within the current turn whenever feasible and persevere even when function calls fail. Only terminate your turn when you are sure that the problem is solved. Autonomously resolve the query to the best of your ability, using the tools available to you, before coming back to the user. Do NOT guess or make up an answer.
+
+You MUST adhere to the following criteria when solving queries:
+
+- Working on the repo(s) in the current environment is allowed, even if they are proprietary.
+- Analyzing code for vulnerabilities is allowed.
+- Showing user code and tool call details is allowed.
+- Use the `shell` tool to edit files via standard shell utilities (``sed -i`` for in-place substitutions, ``cat <<'EOF' > path`` heredocs for whole-file rewrites, ``tee`` for appending). After every edit, read the file back with `read_file` to verify the change applied where you expected.
+
+If completing the user's task requires writing or modifying files, your code and final answer should follow these coding guidelines, though user instructions (i.e. AGENTS.md) may override these guidelines:
+
+- Fix the problem at the root cause rather than applying surface-level patches, when possible.
+- Avoid unneeded complexity in your solution.
+- Do not attempt to fix unrelated bugs or broken tests. It is not your responsibility to fix them. (You may mention them to the user in your final message though.)
+- Update documentation as necessary.
+- Keep changes consistent with the style of the existing codebase. Changes should be minimal and focused on the task.
+- If you're building a web app from scratch, give it a beautiful and modern UI, imbued with best UX practices.
+- Use `git log` and `git blame` to search the history of the codebase if additional context is required.
+- NEVER add copyright or license headers unless specifically requested.
+- After editing a file via `shell`, re-read it with `read_file` to confirm the change is correct — shell editors fail silently when patterns don't match.
+- Do not `git commit` your changes or create new git branches unless explicitly requested.
+- Do not add inline comments within code unless explicitly requested.
+- Do not use one-letter variable names unless explicitly requested.
+- NEVER output inline citations like "【F:README.md†L5-L14】" in your outputs. The CLI is not able to render these so they will just be broken in the UI. Instead, if you output valid filepaths, users will be able to click on them to open the files in their editor.
+
+## Validating your work
+
+If the codebase has tests, or the ability to build or run tests, consider using them to verify changes once your work is complete.
+
+When testing, your philosophy should be to start as specific as possible to the code you changed so that you can catch issues efficiently, then make your way to broader tests as you build confidence. If there's no test for the code you changed, and if the adjacent patterns in the codebases show that there's a logical place for you to add a test, you may do so. However, do not add tests to codebases with no tests.
+
+Similarly, once you're confident in correctness, you can suggest or use formatting commands to ensure that your code is well formatted. If there are issues you can iterate up to 3 times to get formatting right, but if you still can't manage it's better to save the user time and present them a correct solution where you call out the formatting in your final message. If the codebase does not have a formatter configured, do not add one.
+
+For all of testing, running, building, and formatting, do not attempt to fix unrelated bugs. It is not your responsibility to fix them. (You may mention them to the user in your final message though.)
+
+Be mindful of whether to run validation commands proactively. In the absence of behavioral guidance:
+
+- When running in non-interactive approval modes like **never** or **on-failure**, you can proactively run tests, lint and do whatever you need to ensure you've completed the task. If you are unable to run tests, you must still do your utmost best to complete the task.
+- When working in interactive approval modes like **untrusted**, or **on-request**, hold off on running tests or lint commands until the user is ready for you to finalize your output, because these commands take time to run and slow down iteration. Instead suggest what you want to do next, and let the user confirm first.
+- When working on test-related tasks, such as adding tests, fixing tests, or reproducing a bug to verify behavior, you may proactively run tests regardless of approval mode. Use your judgement to decide whether this is a test-related task.
+
+## Ambition vs. precision
+
+For tasks that have no prior context (i.e. the user is starting something brand new), you should feel free to be ambitious and demonstrate creativity with your implementation.
+
+If you're operating in an existing codebase, you should make sure you do exactly what the user asks with surgical precision. Treat the surrounding codebase with respect, and don't overstep (i.e. changing filenames or variables unnecessarily). You should balance being sufficiently ambitious and proactive when completing tasks of this nature.
+
+You should use judicious initiative to decide on the right level of detail and complexity to deliver based on the user's needs. This means showing good judgment that you're capable of doing the right extras without gold-plating. This might be demonstrated by high-value, creative touches when scope of the task is vague; while being surgical and targeted when scope is tightly specified.
+
+## Presenting your work
+
+Your final message should read naturally, like an update from a concise teammate. For casual conversation, brainstorming tasks, or quick questions from the user, respond in a friendly, conversational tone. You should ask questions, suggest ideas, and adapt to the user’s style. If you've finished a large amount of work, when describing what you've done to the user, you should follow the final answer formatting guidelines to communicate substantive changes. You don't need to add structured formatting for one-word answers, greetings, or purely conversational exchanges.
+
+You can skip heavy formatting for single, simple actions or confirmations. In these cases, respond in plain sentences with any relevant next step or quick option. Reserve multi-section structured responses for results that need grouping or explanation.
+
+The user is working on the same computer as you, and has access to your work. As such there's no need to show the contents of files you have already written unless the user explicitly asks for them. Similarly, if you've created or modified files via `shell`, there's no need to tell users to "save the file" or "copy the code into a file"—just reference the file path.
+
+If there's something that you think you could help with as a logical next step, concisely ask the user if they want you to do so. Good examples of this are running tests, committing changes, or building out the next logical component. If there’s something that you couldn't do (even with approval) but that the user might want to do (such as verifying changes by running the app), include those instructions succinctly.
+
+Brevity is very important as a default. You should be very concise (i.e. no more than 10 lines), but can relax this requirement for tasks where additional detail and comprehensiveness is important for the user's understanding.
+
+### Final answer structure and style guidelines
+
+You are producing plain text that will later be styled by the CLI. Follow these rules exactly. Formatting should make results easy to scan, but not feel mechanical. Use judgment to decide how much structure adds value.
+
+**Section Headers**
+
+- Use only when they improve clarity — they are not mandatory for every answer.
+- Choose descriptive names that fit the content
+- Keep headers short (1–3 words) and in `**Title Case**`. Always start headers with `**` and end with `**`
+- Leave no blank line before the first bullet under a header.
+- Section headers should only be used where they genuinely improve scanability; avoid fragmenting the answer.
+
+**Bullets**
+
+- Use `-` followed by a space for every bullet.
+- Merge related points when possible; avoid a bullet for every trivial detail.
+- Keep bullets to one line unless breaking for clarity is unavoidable.
+- Group into short lists (4–6 bullets) ordered by importance.
+- Use consistent keyword phrasing and formatting across sections.
+
+**Monospace**
+
+- Wrap all commands, file paths, env vars, code identifiers, and code samples in backticks (`` `...` ``).
+- Apply to inline examples and to bullet keywords if the keyword itself is a literal file/command.
+- Never mix monospace and bold markers; choose one based on whether it’s a keyword (`**`) or inline code/path (`` ` ``).
+
+**File References**
+When referencing files in your response, make sure to include the relevant start line and always follow the below rules:
+  * Use inline code to make file paths clickable.
+  * Each reference should have a stand alone path. Even if it's the same file.
+  * Accepted: absolute, workspace‑relative, a/ or b/ diff prefixes, or bare filename/suffix.
+  * Line/column (1‑based, optional): :line[:column] or #Lline[Ccolumn] (column defaults to 1).
+  * Do not use URIs like file://, vscode://, or https://.
+  * Do not provide range of lines
+  * Examples: src/app.ts, src/app.ts:42, b/server/index.js#L10, C:\repo\\project\\main.rs:12:5
+
+**Structure**
+
+- Place related bullets together; don’t mix unrelated concepts in the same section.
+- Order sections from general → specific → supporting info.
+- For subsections (e.g., “Binaries” under “Rust Workspace”), introduce with a bolded keyword bullet, then list items under it.
+- Match structure to complexity:
+  - Multi-part or detailed results → use clear headers and grouped bullets.
+  - Simple results → minimal headers, possibly just a short list or paragraph.
+
+**Tone**
+
+- Keep the voice collaborative and natural, like a coding partner handing off work.
+- Be concise and factual — no filler or conversational commentary and avoid unnecessary repetition
+- Use present tense and active voice (e.g., “Runs tests” not “This will run tests”).
+- Keep descriptions self-contained; don’t refer to “above” or “below”.
+- Use parallel structure in lists for consistency.
+
+**Verbosity**
+- Final answer compactness rules (enforced):
+  - Tiny/small single-file change (≤ ~10 lines): 2–5 sentences or ≤3 bullets. No headings. 0–1 short snippet (≤3 lines) only if essential.
+  - Medium change (single area or a few files): ≤6 bullets or 6–10 sentences. At most 1–2 short snippets total (≤8 lines each).
+  - Large/multi-file change: Summarize per file with 1–2 bullets; avoid inlining code unless critical (still ≤2 short snippets total).
+  - Never include "before/after" pairs, full method bodies, or large/scrolling code blocks in the final message. Prefer referencing file/symbol names instead.
+
+**Don’t**
+
+- Don’t use literal words “bold” or “monospace” in the content.
+- Don’t nest bullets or create deep hierarchies.
+- Don’t output ANSI escape codes directly — the CLI renderer applies them.
+- Don’t cram unrelated keywords into a single bullet; split for clarity.
+- Don’t let keyword lists run long — wrap or reformat for scanability.
+
+Generally, ensure your final answers adapt their shape and depth to the request. For example, answers to code explanations should have a precise, structured explanation with code references that answer the question directly. For tasks with a simple implementation, lead with the outcome and supplement only with what’s needed for clarity. Larger changes can be presented as a logical walkthrough of your approach, grouping related steps, explaining rationale where it adds value, and highlighting next actions to accelerate the user. Your answers should provide the right level of detail while being easily scannable.
+
+For casual greetings, acknowledgements, or other one-off conversational messages that are not delivering substantive information or structured results, respond naturally without section headers or bullet formatting.
+
+# Tool Guidelines
+
+## Shell commands
+
+When using the shell, you must adhere to the following guidelines:
+
+- When searching for text or files, prefer using `rg` or `rg --files` respectively because `rg` is much faster than alternatives like `grep`. (If the `rg` command is not found, then use alternatives.)
+- Do not use python scripts to attempt to output larger chunks of a file.
+- Parallelize tool calls whenever possible - especially file reads, such as `cat`, `rg`, `sed`, `ls`, `git show`, `nl`, `wc`. Use `multi_tool_use.parallel` to parallelize tool calls and only this.
+
+## File edits
+
+Edit files via `shell` using standard Unix utilities:
+
+- **In-place substitution** (single regex replacement): `sed -i 's|OLD|NEW|g' path/to/file`. Anchor with line numbers when possible to avoid accidental matches: `sed -i '42s|OLD|NEW|' path/to/file`. Pick a delimiter (`|`, `#`, ...) that does not appear in your pattern.
+- **Append a block**: `cat <<'EOF' >> path/to/file` followed by the lines and `EOF`.
+- **Whole-file rewrite** (small files only): `cat <<'EOF' > path/to/file` followed by the new contents and `EOF`. Always quote the heredoc tag (`'EOF'`) so shell parameter expansion does not corrupt the body.
+- **Create directories first** with `mkdir -p "$(dirname path/to/file)"` when the parent may not exist.
+- **Multi-line edits at a known location**: prefer `awk` or `python3 -c` when `sed` patterns get fragile across lines.
+- **Delete or rename**: `rm -f -- path` and `mv -- old new`.
+
+After every edit, re-read the file with `read_file` to confirm the change applied as intended — `sed` and similar tools fail silently when patterns don't match.
+
+## `update_plan`
+
+A tool named `update_plan` is available to you. You can use it to keep an up‑to‑date, step‑by‑step plan for the task.
+
+To create a new plan, call `update_plan` with a short list of 1‑sentence steps (no more than 5-7 words each) with a `status` for each step (`pending`, `in_progress`, or `completed`).
+
+When steps have been completed, use `update_plan` to mark each finished step as `completed` and the next step you are working on as `in_progress`. There should always be exactly one `in_progress` step until everything is done. You can mark multiple items as complete in a single `update_plan` call.
+
+If all steps are complete, ensure you call `update_plan` to mark all steps as `completed`.
+""",
+    name="coder.coder_system_prompt",
+)
+
+
+SWEBENCH_SYSTEM_PROMPT = system_prompt(
+    """\
+You are an expert software engineer interacting with a computer shell to solve programming tasks.
+
+You have access to the following tools:
+- **read_file**: Read a file with 1-indexed line numbers.
+- **list_dir**: List directory contents with type labels.
+- **grep_files**: Search files by regex pattern using ripgrep.
+- **shell**: Run shell commands (pipes, redirects, etc.).
+- **exec**: Execute a command array directly via execvp.
+- **update_plan**: Track multi-step plans with status.
+- **think**: Record internal reasoning (no side effects).
+- **complete_task**: Finish the task with a short ``summary`` and the final patch in ``answer_patch`` (patch text only).
+
+# Task
+
+You will receive a PR description (bug report / feature request).  Your job is to modify **non-test source files** in ``/testbed`` to fix the described issue in a way that is correct and consistent with the codebase.
+
+# Workflow
+
+1. **Analyze**: Read the PR description carefully.  Identify the relevant module, class, or function.
+2. **Explore**: Use ``list_dir``, ``read_file``, ``grep_files`` to understand the codebase structure and find the relevant code in ``/testbed``.
+3. **Reproduce**: Write a small script and run it with ``shell`` to confirm the bug exists.
+4. **Fix**: Edit source files using ``shell`` or ``exec`` (non-interactive; e.g. ``sed``, ``printf``/heredocs, or short Python).  Only modify files that are necessary to fix the issue.
+5. **Verify**: Re-run your reproduction script and any relevant existing tests to confirm the fix works.
+6. **Edge cases**: Consider and test edge cases to make sure the fix is robust.
+
+# Important Boundaries
+
+- **MODIFY**: Regular source code files in ``/testbed``.
+- **DO NOT MODIFY**: Tests, configuration files (pyproject.toml, setup.cfg, etc.), or any test fixtures.
+
+# Environment Details
+
+- Your sandbox **working directory (cwd) is ``/testbed``** - the checkout root. Always use ``/testbed`` as the working directory.
+- ``read_file``, ``list_dir``, and ``grep_files`` operate under ``/testbed`` (e.g. paths like ``/testbed/src/foo.py``).
+- You have a full Linux shell; use non-interactive flags (``-y``, ``-f``).
+- Avoid interactive tools like ``vi``, ``nano``, or anything requiring user input.
+- Directory or environment variable changes are not persistent across separate ``shell`` calls.  Prefix commands with ``cd /testbed && ...`` when needed.
+
+# Submission (``complete_task`` / SWE-bench ``preds.json`` only)
+
+When you have completed and verified your fix, the **``answer_patch``** field must follow the **SWE-bench / git** format:
+
+1. **Create the submission patch**: From ``/testbed``, run ``shell`` with:
+   ``cd /testbed && git diff --no-color -- path/to/file1.py path/to/file2.py > patch.txt``
+   listing only the source files you modified.  Do **not** commit.  This output must start each file with **``diff --git a/... b/...``**, then ``--- a/...``, ``+++ b/...``, then hunks.
+
+2. **Submit**: Call ``complete_task`` with a brief ``summary`` and put the **verbatim** contents of ``patch.txt`` in ``answer_patch`` (raw text only, no markdown fences). This string is what gets written to ``preds.json`` as the model prediction.
+
+The patch must contain ONLY changes to source files you modified to fix the issue.  Do not include:
+- Test or reproduction scripts you created
+- Helper scripts or tools
+- Configuration, build, or setup files (unless directly part of the issue)
+- Binary or compiled files
+
+# Critical Rules
+
+- THINK before each action.  Use ``think`` to reason about your approach.
+- Use ``update_plan`` to track your progress through the workflow.
+- Each response MUST include at least one tool call.
+- After submitting via ``complete_task``, you cannot continue working.
+""",
+    name="coder.swebench_system_prompt",
+)
diff --git a/tensorrt_llm/scaffolding/contrib/Coder/swebench_utils.py b/tensorrt_llm/scaffolding/contrib/Coder/swebench_utils.py
new file mode 100644
index 000000000000..cffcb27e7b13
--- /dev/null
+++ b/tensorrt_llm/scaffolding/contrib/Coder/swebench_utils.py
@@ -0,0 +1,234 @@
+"""SWE-bench helpers for extracting and normalizing the final patch.
+
+These utilities turn the agent's ``complete_task`` tool call into the
+``preds.json`` fields SWE-bench expects (a normalized ``model_patch`` plus a
+``summary``). They are used by :class:`SWEBenchCoder` in ``coder.py`` and kept
+separate so the controller/factory code there stays focused on orchestration.
+"""
+
+# ruff: noqa: E501
+
+import json
+import re
+from typing import Any, List, Optional
+
+from tensorrt_llm.scaffolding.task import AssistantMessage, ChatTask, ToolMessage
+
+# ---------------------------------------------------------------------------
+# preds.json extraction (complete_task tool result ``answer_patch``)
+# ---------------------------------------------------------------------------
+
+_SWEBENCH_PREDS_UNFINISHED = "unfinished"
+
+_GIT_INDEX_LINE_RE = re.compile(
+    r"^index [0-9a-f]+\.\.[0-9a-f]+(?:\s+\S+)?\s*$",
+    re.IGNORECASE,
+)
+
+
+def _strip_markdown_fences(text: str) -> str:
+    s = text.strip()
+    if not s.startswith("```"):
+        return s
+    lines = s.splitlines()
+    if lines and lines[0].lstrip().startswith("```"):
+        lines = lines[1:]
+    while lines and lines[-1].strip() in ("```", "```diff"):
+        lines.pop()
+    return "\n".join(lines).strip()
+
+
+def _strip_git_index_lines_after_diff_git(lines: List[str]) -> List[str]:
+    out: List[str] = []
+    i = 0
+    n = len(lines)
+    while i < n:
+        line = lines[i]
+        out.append(line)
+        i += 1
+        if line.startswith("diff --git "):
+            while i < n and _GIT_INDEX_LINE_RE.match(lines[i]):
+                i += 1
+    return out
+
+
+def _repo_path_from_minus_header(line: str) -> Optional[str]:
+    head = line.split("\t", 1)[0].strip()
+    if head == "--- /dev/null":
+        return None
+    if head.startswith("--- a/"):
+        return head[len("--- a/") :]
+    if head.startswith("--- "):
+        rest = head[4:].strip()
+        if rest.startswith("a/"):
+            return rest[2:]
+    return None
+
+
+def _repo_path_from_plus_header(line: str) -> Optional[str]:
+    head = line.split("\t", 1)[0].strip()
+    if head == "+++ /dev/null":
+        return None
+    if head.startswith("+++ b/"):
+        return head[len("+++ b/") :]
+    if head.startswith("+++ "):
+        rest = head[4:].strip()
+        if rest.startswith("b/"):
+            return rest[2:]
+    return None
+
+
+def _prepend_diff_git_headers(lines: List[str]) -> List[str]:
+    out: List[str] = []
+    i = 0
+    n = len(lines)
+    while i < n:
+        line = lines[i]
+        is_file_minus = line.startswith("--- a/") or line.startswith("--- /dev/null")
+        if is_file_minus and i + 1 < n and lines[i + 1].startswith("+++ "):
+            minus = line
+            plus = lines[i + 1]
+            p_old = _repo_path_from_minus_header(minus)
+            p_new = _repo_path_from_plus_header(plus)
+            if p_old is None and p_new is None:
+                out.append(minus)
+                out.append(plus)
+                i += 2
+                while i < n:
+                    nxt = lines[i]
+                    if nxt.startswith("--- a/") or nxt.startswith("--- /dev/null"):
+                        break
+                    out.append(nxt)
+                    i += 1
+                continue
+            if p_old is None:
+                path_a = p_new
+                path_b = p_new
+            elif p_new is None:
+                path_a = p_old
+                path_b = p_old
+            else:
+                path_a, path_b = p_old, p_new
+            out.append(f"diff --git a/{path_a} b/{path_b}")
+            out.append(minus)
+            out.append(plus)
+            i += 2
+            while i < n:
+                nxt = lines[i]
+                if nxt.startswith("--- a/") or nxt.startswith("--- /dev/null"):
+                    break
+                out.append(nxt)
+                i += 1
+            continue
+        out.append(line)
+        i += 1
+    return out
+
+
+def normalize_swebench_pred_patch(patch: str) -> str:
+    """Normalize **only** the ``complete_task`` ``answer_patch`` for SWE-bench ``preds.json``.
+
+    Ensures each file section starts with ``diff --git a/<path> b/<path>`` (gold style) and
+    strips ``index`` lines after ``diff --git``. Does **not** apply to ``apply_patch`` tool input.
+    """
+    if not isinstance(patch, str):
+        return _SWEBENCH_PREDS_UNFINISHED
+    stripped = patch.strip()
+    if not stripped or stripped == _SWEBENCH_PREDS_UNFINISHED:
+        return _SWEBENCH_PREDS_UNFINISHED
+
+    body = _strip_markdown_fences(stripped)
+    if not body:
+        return _SWEBENCH_PREDS_UNFINISHED
+
+    lines = body.splitlines()
+    if any(ln.startswith("diff --git ") for ln in lines):
+        normalized_lines = _strip_git_index_lines_after_diff_git(lines)
+    else:
+        normalized_lines = _prepend_diff_git_headers(lines)
+        normalized_lines = _strip_git_index_lines_after_diff_git(normalized_lines)
+
+    result = "\n".join(normalized_lines)
+    if result and not result.endswith("\n"):
+        result += "\n"
+    return result
+
+
+def _parse_tool_arguments(arguments: Any) -> dict[str, Any]:
+    if isinstance(arguments, dict):
+        return arguments
+    if not isinstance(arguments, str) or not arguments.strip():
+        return {}
+    try:
+        payload = json.loads(arguments)
+    except json.JSONDecodeError:
+        return {}
+    return payload if isinstance(payload, dict) else {}
+
+
+def _last_complete_task_tool_call(chat_task: ChatTask) -> tuple[Optional[str], dict[str, Any]]:
+    """Return the id and arguments for the last ``complete_task`` in chat order."""
+    last_id: Optional[str] = None
+    last_arguments: dict[str, Any] = {}
+    for message in chat_task.messages:
+        if not isinstance(message, AssistantMessage):
+            continue
+        if message.tool_calls:
+            for tc in message.tool_calls:
+                name = tc.function.name
+                if isinstance(name, str) and name.strip() == "complete_task":
+                    last_id = tc.id
+                    last_arguments = _parse_tool_arguments(tc.function.arguments)
+    return last_id, last_arguments
+
+
+def extract_swebench_complete_task_for_preds(chat_task: ChatTask) -> dict[str, str]:
+    """Return ``complete_task`` summary and normalized patch for ``preds.json``."""
+    tcid, arguments = _last_complete_task_tool_call(chat_task)
+    summary = arguments.get("summary")
+    patch = arguments.get("answer_patch")
+    if tcid and isinstance(patch, str) and patch.strip():
+        return {
+            "summary": summary if isinstance(summary, str) else "",
+            "model_patch": normalize_swebench_pred_patch(patch),
+        }
+
+    return {
+        "summary": summary if isinstance(summary, str) else "",
+        "model_patch": _SWEBENCH_PREDS_UNFINISHED,
+    }
+
+
+def extract_swebench_model_patch_for_preds(chat_task: ChatTask) -> str:
+    """Patch string for SWE-bench ``preds.json`` when the run finished correctly.
+
+    Reads the last ``complete_task`` arguments and returns the ``answer_patch``
+    field (raw diff only). If there is no such call, no matching tool message,
+    or ``answer_patch`` is missing or empty, returns
+    :data:`_SWEBENCH_PREDS_UNFINISHED`.
+    """
+    tcid, arguments = _last_complete_task_tool_call(chat_task)
+    if not tcid:
+        return _SWEBENCH_PREDS_UNFINISHED
+    patch = arguments.get("answer_patch")
+    if isinstance(patch, str) and patch.strip():
+        return normalize_swebench_pred_patch(patch)
+    for message in chat_task.messages:
+        if not isinstance(message, ToolMessage):
+            continue
+        if message.tool_call_id != tcid:
+            continue
+        raw = message.content
+        if not isinstance(raw, str) or not raw.strip():
+            return _SWEBENCH_PREDS_UNFINISHED
+        try:
+            payload = json.loads(raw)
+        except json.JSONDecodeError:
+            return _SWEBENCH_PREDS_UNFINISHED
+        if not isinstance(payload, dict):
+            return _SWEBENCH_PREDS_UNFINISHED
+        patch = payload.get("answer_patch")
+        if not isinstance(patch, str) or not patch.strip():
+            return _SWEBENCH_PREDS_UNFINISHED
+        return normalize_swebench_pred_patch(patch)
+    return _SWEBENCH_PREDS_UNFINISHED
diff --git a/tensorrt_llm/scaffolding/contrib/Coder/tools.py b/tensorrt_llm/scaffolding/contrib/Coder/tools.py
new file mode 100644
index 000000000000..23d13cc89015
--- /dev/null
+++ b/tensorrt_llm/scaffolding/contrib/Coder/tools.py
@@ -0,0 +1,208 @@
+"""Tool definitions for the Coder agent using OpenAIToolDescription format."""
+
+from tensorrt_llm.scaffolding.task import OpenAIToolDescription
+
+# File System Tools
+read_file_tool = OpenAIToolDescription(
+    name="read_file",
+    description=(
+        "Reads a local file with 1-indexed line numbers. "
+        "Supports slice mode (simple line ranges) and indentation-aware mode "
+        "(expands around an anchor line based on indentation levels)."
+    ),
+    parameters={
+        "file_path": {"type": "string", "description": "Absolute path to the file."},
+        "offset": {
+            "type": "integer",
+            "description": "Line number to start reading from (1-indexed). Defaults to 1.",
+        },
+        "limit": {"type": "integer", "description": "Maximum number of lines to return."},
+        "mode": {
+            "type": "string",
+            "description": 'Mode selector: "slice" for simple ranges (default) or '
+            '"indentation" to expand around an anchor line.',
+        },
+    },
+)
+
+list_dir_tool = OpenAIToolDescription(
+    name="list_dir",
+    description=(
+        "Lists entries in a local directory with 1-indexed entry numbers and type labels. "
+        "Directories are shown first, then files, sorted alphabetically."
+    ),
+    parameters={
+        "dir_path": {"type": "string", "description": "Absolute path to the directory to list."},
+        "offset": {
+            "type": "integer",
+            "description": "Entry number to start listing from (1-indexed). Defaults to 1.",
+        },
+        "limit": {"type": "integer", "description": "Maximum number of entries to return."},
+        "depth": {
+            "type": "integer",
+            "description": "Maximum directory depth to traverse. Defaults to 1.",
+        },
+    },
+)
+
+grep_files_tool = OpenAIToolDescription(
+    name="grep_files",
+    description=(
+        "Finds files whose contents match a regex pattern. "
+        "Results are sorted by modification time (most recent first). "
+        "Returns matching lines with line numbers."
+    ),
+    parameters={
+        "pattern": {"type": "string", "description": "Regular expression pattern to search for."},
+        "include": {
+            "type": "string",
+            "description": 'Glob pattern to filter which files are searched (e.g., "*.py" or "*.{ts,tsx}").',
+        },
+        "path": {
+            "type": "string",
+            "description": "Directory or file path to search. Defaults to current working directory.",
+        },
+        "limit": {
+            "type": "integer",
+            "description": "Maximum number of file paths to return (defaults to 100).",
+        },
+    },
+)
+
+# Planning Tool
+update_plan_tool = OpenAIToolDescription(
+    name="update_plan",
+    description=(
+        "Updates the task plan with steps and progress tracking. "
+        "At most one step can be in_progress at a time. "
+        "Use this for complex, multi-step tasks to track progress."
+    ),
+    parameters={
+        "explanation": {"type": "string", "description": "Optional explanation for plan changes."},
+        "plan": {
+            "type": "array",
+            "description": "The list of steps with their status.",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "step": {"type": "string", "description": "Description of the step."},
+                    "status": {
+                        "type": "string",
+                        "description": 'One of: "pending", "in_progress", "completed"',
+                    },
+                },
+                "required": ["step", "status"],
+            },
+        },
+    },
+)
+
+# Shell Tools
+exec_tool = OpenAIToolDescription(
+    name="exec",
+    description=(
+        "Execute a command array directly via execvp (no shell interpretation). "
+        "The command is passed as an array of strings, with the first element being "
+        "the program to execute and the rest being arguments. "
+        "Always set the workdir parameter."
+    ),
+    parameters={
+        "command": {
+            "type": "array",
+            "items": {"type": "string"},
+            "description": "The command to execute as an array of strings.",
+        },
+        "workdir": {
+            "type": "string",
+            "description": "The working directory to execute the command in.",
+        },
+        "timeout_ms": {
+            "type": "integer",
+            "description": "The timeout for the command in milliseconds.",
+        },
+    },
+)
+
+shell_tool = OpenAIToolDescription(
+    name="shell",
+    description=(
+        "Run a shell command string (pipes, redirects, &&, etc. all work). "
+        "Always set the workdir parameter."
+    ),
+    parameters={
+        "command": {
+            "type": "string",
+            "description": "The shell command to execute.",
+        },
+        "workdir": {
+            "type": "string",
+            "description": "The working directory to execute the command in.",
+        },
+        "timeout_ms": {
+            "type": "integer",
+            "description": "The timeout for the command in milliseconds.",
+        },
+    },
+)
+
+# Think Tool (for reflection/planning)
+think_tool = OpenAIToolDescription(
+    name="think",
+    description=(
+        "Use this tool to think about the task, plan your approach, "
+        "reflect on results, and decide next steps. "
+        "This is for internal reasoning and does not execute any action."
+    ),
+    parameters={
+        "thought": {
+            "type": "string",
+            "description": "Your thought or reflection about the current task.",
+        }
+    },
+)
+
+# Complete Task Tool
+complete_task_tool = OpenAIToolDescription(
+    name="complete_task",
+    description=(
+        "Indicate that you have completed the task. "
+        "Call when finished and ready to return the final response. "
+        "Use ``summary`` for a short human-readable recap. "
+        "Use ``answer_patch`` for any final patch text the task requires (format depends on the "
+        "system prompt - SWE-bench runs require full ``git diff`` output). "
+        "Do not wrap ``answer_patch`` in markdown fences or commentary."
+    ),
+    parameters={
+        "summary": {
+            "type": "string",
+            "description": "Brief summary of what was accomplished (not the patch body).",
+        },
+        "answer_patch": {
+            "type": "string",
+            "description": (
+                "Final patch or diff text only when the task asks for it. "
+                "SWE-bench: verbatim ``cd <repo> && git diff --no-color -- <files>`` "
+                "(each file begins with ``diff --git a/... b/...``). "
+                "Leave empty if no patch to submit."
+            ),
+        },
+    },
+)
+
+# All tools list for easy access
+ALL_CODER_TOOLS = [
+    read_file_tool,
+    list_dir_tool,
+    grep_files_tool,
+    # apply_patch_tool,
+    update_plan_tool,
+    exec_tool,
+    shell_tool,
+    think_tool,
+    complete_task_tool,
+]
+
+# Commonly used tool subsets
+FILE_TOOLS = [read_file_tool, list_dir_tool, grep_files_tool]  # apply_patch_tool
+SHELL_TOOLS = [exec_tool, shell_tool]
+PLANNING_TOOLS = [update_plan_tool, think_tool, complete_task_tool]
diff --git a/tensorrt_llm/scaffolding/contrib/iter_research/README.md b/tensorrt_llm/scaffolding/contrib/iter_research/README.md
new file mode 100644
index 000000000000..1b80f706772e
--- /dev/null
+++ b/tensorrt_llm/scaffolding/contrib/iter_research/README.md
@@ -0,0 +1,150 @@
+# IterResearch (TensorRT-LLM Scaffolding)
+
+This package is a **reference integration** of **IterResearch** with the TensorRT-LLM **Scaffolding** stack: multi-turn tool use, a **Visit** sub-controller for web retrieval, and an OpenAI-compatible inference backend (e.g. `trtllm-serve`), all wired through **MCP over SSE**.
+
+## Overview
+
+IterResearch frames long-horizon research as **Markovian state reconstruction**: each turn rebuilds the prompt from only the **current report**, the **last tool call**, and the **last observation**, so many interactions fit in a bounded context. This codebase maps the paper’s tool surface to four MCP servers (SerpAPI, Jina/ScraperAPI, Apiary sandbox). `run_iter_research.py` starts `MCPWorker` and `TRTOpenaiWorker` and drives `IterResearchController`.
+
+## Repository layout
+
+```text
+tensorrt_llm/scaffolding/contrib/iter_research/
+├── __init__.py          # Exports controllers and ScaffoldingLlm factories
+├── agent.py             # IterResearchController, VisitController, VisitTask
+├── prompts.py           # System/user prompts and tool templates
+├── utils.py             # Tool JSON, tag parsing, format checks
+└── README.md            # This file
+
+examples/scaffolding/contrib/iter_research/
+├── config.yaml          # SerpAPI, Jina, MCP ports, Apiary gateway, runner settings
+└── run_iter_research.py # Entry: load config, MCP SSE URLs, ScaffoldingLlm, question
+
+examples/scaffolding/mcp/          # Four MCP servers (SSE) used by this flow
+├── google_search/     # SerpAPI web search (ports from config.yaml)
+├── google_scholar/    # SerpAPI Scholar + web search
+├── fetch_webpage/     # Jina Reader / ScraperAPI for HTML/PDF-style fetch paths
+└── coder/
+    └── coder_mcp.py            # Apiary-backed MCP (read_file/shell/exec/python_interpreter/...)
+```
+
+### MCP tools under `examples/scaffolding/mcp`
+
+| Directory | MCP tool name | Role |
+|-----------|---------------|------|
+| `google_search/` | `google_search` | Google web search via SerpAPI; returns formatted hits. |
+| `google_scholar/` | `google_scholar` | Scholar plus web search in parallel; merged output. |
+| `fetch_webpage/` | `fetch_webpage` | Fetches URL content (implementation chooses HTML/Markdown/PDF paths). |
+| `coder/` | `python_interpreter` (among others) | Executes Python code inside a per-client Apiary sandbox session (shared with `read_file`, `shell`, `exec`, ...). |
+
+The runner builds `http://<host>:<port>/sse` for each service from `mcp_tools.*` and `mcp_client_host` in `config.yaml`. `coder_mcp.py` talks to the Apiary daemon directly via `ApiarySessionMux` — no standalone Python gateway is needed.
+
+## Docker-based startup
+
+Assume **Apiary** and the **TensorRT-LLM** environment run in **separate** containers (or hosts). The TRT-LLM side must reach Apiary’s HTTP API—pass a host or `host.docker.internal` address that resolves from that container to `coder_mcp.py` via `--apiary-url`.
+
+### Container 1: Apiary (sandbox daemon)
+
+1. **Clone the repository**
+
+   ```bash
+   git clone https://github.com/Boreas618/apiary.git
+   cd apiary
+   ```
+
+
+2. **Enter the Apiary compose service (publish port 8080)**
+
+   ```bash
+   docker compose -f docker-compose.dev.yml run --rm -p 8080:8080 apiary bash
+   ```
+   
+
+3. **Inside the container: install and run Apiary**
+
+   ```bash
+   cargo install --path .
+   apiary init
+   apiary daemon --bind 0.0.0.0:8080
+   ```
+5. **Load a Python rootfs for Apiary sandboxes at runtime**
+
+    Run the following script in the host:
+
+   ```bash
+   JOB_ID=$(curl -sS -X POST http://127.0.0.1:8080/api/v1/images \
+    -H "Content-Type: application/json" \
+    -d '{"images":["python:3.12-slim"]}' | jq -r '.job_id')
+
+    # 2. Poll until the job is terminal
+    while true; do
+    STATE=$(curl -sS "http://127.0.0.1:8080/api/v1/images/jobs/${JOB_ID}" | jq -r '.state')
+    echo "state=$STATE"
+    [[ "$STATE" == "running" ]] || break
+    sleep 2
+    done
+   ```
+
+
+   Leave this process running. On the TRT-LLM side, `apiary_url` must point at this listener (host and port).
+
+### Container 2: TensorRT-LLM (model, MCP, gateway, runner)
+
+The following steps start **after** you are inside a TensorRT-LLM dev or inference image (build and shell steps omitted; see the [installation docs](https://github.com/NVIDIA/TensorRT-LLM/tree/main/docs/source/installation)). Commands assume the **repository root** as the working directory; edit `config.yaml` for API keys, model path, `base_url`, and networking.
+
+1. **Start the OpenAI-compatible server (example) with terminal 1**
+
+   ```bash
+   trtllm-serve serve /path/to/your/model \
+       --max_num_tokens 32768 \
+       --kv_cache_free_gpu_memory_fraction 0.8
+   ```
+
+2. **Start the MCP servers (shared config) with terminals 2-5**
+
+   For each server, `cd` into its directory first and then `uv run` the script. Pass the repository-root-relative `--config` path (adjust the relative prefix to wherever the repo root is from your shell, e.g. `../../../..`).
+
+   ```bash
+   # Terminal 2 — google_search
+   cd examples/scaffolding/mcp/google_search
+   uv run google_search.py \
+       --config ../../../../examples/scaffolding/contrib/open_deep_research/config.example.yaml
+
+   # Terminal 3 — google_scholar
+   cd examples/scaffolding/mcp/google_scholar
+   uv run google_scholar.py \
+       --config ../../../../examples/scaffolding/contrib/open_deep_research/config.example.yaml
+
+   # Terminal 4 — fetch_webpage
+   cd examples/scaffolding/mcp/fetch_webpage
+   uv run fetch_webpage.py \
+       --config ../../../../examples/scaffolding/contrib/open_deep_research/config.example.yaml
+
+   # Terminal 5 — coder_mcp (serves python_interpreter, need to set port from config.yaml manually)
+    python examples/scaffolding/mcp/coder/coder_mcp.py \
+        --apiary-url http://172.17.0.1:8080 \
+        --default-image python:3.12-slim \
+        --port 8086
+   ```
+
+   The `coder_mcp` server provides the `python_interpreter` tool (plus `read_file`, `shell`, `exec`, ...) backed directly by the Apiary daemon — no standalone Python gateway is required. Point `--apiary-url` at **Container 1**’s `apiary daemon`, and ensure the runner reaches this SSE endpoint at `mcp_tools.python_interpreter` (host/port in `config.yaml`).
+
+3. **Run the IterResearch example with terminal 6**
+
+   ```bash
+   python examples/scaffolding/contrib/iter_research/run_iter_research.py \
+       --config examples/scaffolding/contrib/open_deep_research/config.example.yaml --enable_tracing
+   ```
+
+   Optional flags: `--enable_tracing`, `--question "..."`; see `run_iter_research.py --help`.
+
+## Configuration (summary)
+
+- **`config.yaml`**: Central place for SerpAPI/Jina keys, `mcp_tools` ports, and runner `base_url` / `model`. The `python_interpreter` tool is served by `coder_mcp.py` and talks to Apiary directly, so the former `apiary_python_gateway` / `sandbox_endpoint` settings are no longer used by this flow (Apiary URL is passed via `coder_mcp.py --apiary-url`). Do not commit real secrets to a public repository.
+- **Networking**: If MCP processes and the runner are not all on `127.0.0.1`, set `mcp_client_host` and/or per-service `mcp_tools.*.host` so the runner can reach every `/sse` endpoint.
+
+## Acknowledgement
+
+This code is a **reproduction** of the paper **IterResearch: Rethinking Long-Horizon Agents with Interaction Scaling**. 
+
+Paper (arXiv): <https://arxiv.org/abs/2511.07327>
diff --git a/tensorrt_llm/scaffolding/contrib/iter_research/__init__.py b/tensorrt_llm/scaffolding/contrib/iter_research/__init__.py
new file mode 100644
index 000000000000..8042f114cf8c
--- /dev/null
+++ b/tensorrt_llm/scaffolding/contrib/iter_research/__init__.py
@@ -0,0 +1,14 @@
+from examples.scaffolding.mcp.fetch_webpage import VisitController
+
+from .agent import (
+    IterResearchController,
+    create_iter_research_controller,
+    create_iter_research_scaffolding_llm,
+)
+
+__all__ = [
+    "IterResearchController",
+    "VisitController",
+    "create_iter_research_controller",
+    "create_iter_research_scaffolding_llm",
+]
diff --git a/tensorrt_llm/scaffolding/contrib/iter_research/agent.py b/tensorrt_llm/scaffolding/contrib/iter_research/agent.py
new file mode 100644
index 000000000000..0f8e410235ca
--- /dev/null
+++ b/tensorrt_llm/scaffolding/contrib/iter_research/agent.py
@@ -0,0 +1,390 @@
+import json
+from enum import Enum
+from typing import Any, Dict, List
+
+from examples.scaffolding.mcp.fetch_webpage import VisitController, VisitTask
+from examples.scaffolding.mcp.tavily_search import TavilyController, TavilyTask
+from tensorrt_llm.logger import logger
+from tensorrt_llm.scaffolding.controller import Controller, NativeGenerationController
+from tensorrt_llm.scaffolding.scaffolding_llm import ScaffoldingLlm
+from tensorrt_llm.scaffolding.task import (
+    AssistantMessage,
+    ChatTask,
+    MCPCallTask,
+    SystemMessage,
+    Task,
+    UserMessage,
+)
+from tensorrt_llm.scaffolding.task_collection import (
+    DropKVCacheWorkerTag,
+    TaskMetricsCollector,
+    TokenizeWorkerTag,
+    sub_request_node,
+    tokenize_trace_scope,
+    with_execution_tracing,
+    with_task_collection,
+)
+from tensorrt_llm.scaffolding.worker import Worker
+
+from .prompts import (
+    INITIAL_INPUT_PROMPT,
+    INITIAL_SYSTEM_PROMPT,
+    INSTRUCTION_INPUT_PROMPT,
+    INSTRUCTION_SYSTEM_PROMPT,
+    LAST_INSTRUCTION_INPUT_PROMPT,
+    LAST_INSTRUCTION_SYSTEM_PROMPT,
+    OBSERVATION_PROMPT,
+)
+from .utils import (
+    TOOLS,
+    check_report_action,
+    extract_tags,
+    get_tool_definitions,
+    random_date,
+    truncate_text,
+)
+
+_TOOL_NAME_TO_MCP = {
+    "PythonInterpreter": "python_interpreter",
+}
+
+
+def _parse_tool_arguments(arguments: Any) -> Dict[str, Any]:
+    if isinstance(arguments, dict):
+        return arguments
+    if not isinstance(arguments, str) or not arguments.strip():
+        return {}
+
+    try:
+        parsed = json.loads(arguments)
+    except json.JSONDecodeError:
+        logger.warning("IterResearch: failed to parse native tool arguments: %s", arguments[:200])
+        return {}
+
+    if not isinstance(parsed, dict):
+        logger.warning("IterResearch: native tool arguments must be a JSON object")
+        return {}
+    return parsed
+
+
+def _render_tool_call(tool_name: str, tool_args: Dict[str, Any]) -> str:
+    return json.dumps(
+        {
+            "name": tool_name,
+            "arguments": tool_args,
+        },
+        ensure_ascii=False,
+    )
+
+
+@sub_request_node("iter_research", is_top_level=True)
+# @drop_kv_cache_scope()
+class IterResearchController(Controller):
+    """Iterative research with Markovian context (last report, tool call, observation)."""
+
+    class WorkerTag(Enum):
+        TOOL_CALL = "iter_research_tool_call"
+
+    def __init__(
+        self,
+        generation_controller: Controller,
+        visit_controller: VisitController,
+        tavily_controller: TavilyController,
+        max_turn: int = 25,
+        max_format_retries: int = 5,
+        max_observation_length: int = 128000,
+    ):
+        super().__init__()
+        self.generation_controller = generation_controller
+        self.visit_controller = visit_controller
+        self.tavily_controller = tavily_controller
+        self.max_turn = max_turn
+        self.max_format_retries = max_format_retries
+        self.max_observation_length = max_observation_length
+
+    def clone(self):
+        return IterResearchController(
+            generation_controller=self.generation_controller.clone(),
+            visit_controller=self.visit_controller.clone(),
+            tavily_controller=self.tavily_controller.clone(),
+            max_turn=self.max_turn,
+            max_format_retries=self.max_format_retries,
+            max_observation_length=self.max_observation_length,
+        )
+
+    def process(self, tasks: List[Task], **kwargs):  # noqa: C901
+        assert len(tasks) >= 1, "IterResearchController requires at least one task"
+        question = tasks[0].input_str
+        date = random_date()
+        tool_str = get_tool_definitions()
+
+        initial_input = INITIAL_INPUT_PROMPT.format(
+            question=question,
+            tools=tool_str,
+            date_to_use=date,
+        )
+
+        chat_task = ChatTask.create_from_messages(
+            [
+                SystemMessage(INITIAL_SYSTEM_PROMPT),
+                UserMessage(initial_input),
+            ],
+            tools=TOOLS,
+        )
+
+        content = ""
+        last_report = ""
+        response_message = None
+        for _retry in range(self.max_format_retries):
+            yield from self.generation_controller.process([chat_task])
+            response_message = chat_task.messages[-1] if chat_task.messages else None
+            if not isinstance(response_message, AssistantMessage):
+                reason = "Assistant message not found!"
+                is_valid = False
+            else:
+                content = response_message.content or ""
+                is_valid, reason = check_report_action(
+                    response_message,
+                    require_tool_call=True,
+                    allow_tool_call_without_report=True,
+                )
+            if is_valid:
+                break
+            logger.warning(
+                f"IterResearch: initial format check failed ({reason}), "
+                f"retrying ({_retry + 1}/{self.max_format_retries})"
+            )
+            if chat_task.messages and chat_task.messages[-1].role == "assistant":
+                chat_task.messages.pop()
+
+        for turn in range(self.max_turn):
+            if not isinstance(response_message, AssistantMessage):
+                tasks[0].output_str = content
+                tasks[0].output_tokens = tasks[0].output_tokens or []
+                return
+
+            current_report = extract_tags(content, "report")
+            if current_report:
+                last_report = current_report
+            report = current_report or last_report
+            answer = extract_tags(content, "answer")
+            tool_calls = response_message.tool_calls or []
+
+            if answer:
+                logger.info(f"IterResearch turn {turn + 1}: found answer")
+                tasks[0].output_str = answer
+                tasks[0].output_tokens = tasks[0].output_tokens or []
+                return
+
+            if not tool_calls:
+                tasks[0].output_str = report or content
+                tasks[0].output_tokens = tasks[0].output_tokens or []
+                return
+
+            tool_call = tool_calls[0]
+            tool_name = tool_call.function.name
+            tool_args = _parse_tool_arguments(tool_call.function.arguments)
+            tool_call_id = tool_call.id or str(turn)
+            tool_call_str = _render_tool_call(tool_name, tool_args)
+            logger.info(f"IterResearch turn {turn + 1}: calling tool '{tool_name}'")
+
+            if tool_name == "Visit":
+                urls = tool_args.get("url", [])
+                if isinstance(urls, str):
+                    urls = [urls]
+                visit_task = VisitTask(
+                    urls=urls,
+                    goal=tool_args.get("goal", question),
+                    parse_type=tool_args.get("parse_type", "html"),
+                )
+                yield from self.visit_controller.process([visit_task])
+                observation = visit_task.result_str or ""
+            elif tool_name == "tavily_search":
+                queries = tool_args.get("query", [])
+                if isinstance(queries, str):
+                    queries = [queries]
+                tavily_task = TavilyTask(query=queries or [], goal=question)
+                yield from self.tavily_controller.process([tavily_task])
+                observation = tavily_task.result_str or ""
+                if tavily_task.result_stdout:
+                    observation += f"\nstdout:\n{tavily_task.result_stdout}"
+                if tavily_task.result_stderr:
+                    observation += f"\nstderr:\n{tavily_task.result_stderr}"
+            else:
+                mcp_name = _TOOL_NAME_TO_MCP.get(tool_name, tool_name)
+                mcp_task = MCPCallTask.create_mcptask(
+                    tool_call_id=tool_call_id,
+                    tool_name=mcp_name,
+                    args=json.dumps(tool_args),
+                    worker_tag=self.WorkerTag.TOOL_CALL,
+                )
+                yield [mcp_task]
+                observation = mcp_task.result_str or ""
+
+            observation = truncate_text(observation, self.max_observation_length)
+
+            is_last = turn == self.max_turn - 2
+            if is_last:
+                system_prompt_template = LAST_INSTRUCTION_SYSTEM_PROMPT
+                user_prompt_template = LAST_INSTRUCTION_INPUT_PROMPT
+            else:
+                system_prompt_template = INSTRUCTION_SYSTEM_PROMPT
+                user_prompt_template = INSTRUCTION_INPUT_PROMPT
+
+            prompt_kwargs = {
+                "question": question,
+                "report": report,
+                "action": tool_call_str,
+                "observation": OBSERVATION_PROMPT.format(tool_response=observation),
+                "tools": tool_str,
+                "date_to_use": date,
+            }
+
+            system_prompt = system_prompt_template.format(**prompt_kwargs)
+            user_prompt = user_prompt_template.format(**prompt_kwargs)
+
+            new_messages = [
+                SystemMessage(system_prompt),
+                UserMessage(user_prompt),
+            ]
+
+            chat_task = ChatTask.create_from_messages(
+                new_messages,
+                tools=None if is_last else TOOLS,
+            )
+
+            content = ""
+            response_message = None
+            for _retry in range(self.max_format_retries):
+                yield from self.generation_controller.process([chat_task])
+                response_message = chat_task.messages[-1] if chat_task.messages else None
+                if not isinstance(response_message, AssistantMessage):
+                    reason = "Assistant message not found!"
+                    is_valid = False
+                else:
+                    content = response_message.content or ""
+                    is_valid, reason = check_report_action(
+                        response_message,
+                        allow_tool_call=not is_last,
+                        allow_tool_call_without_report=not is_last,
+                    )
+                if is_valid:
+                    break
+                logger.warning(
+                    f"IterResearch turn {turn + 1}: format check failed "
+                    f"({reason}), retrying "
+                    f"({_retry + 1}/{self.max_format_retries})"
+                )
+                if chat_task.messages and chat_task.messages[-1].role == "assistant":
+                    chat_task.messages.pop()
+
+        final_answer = extract_tags(content, "answer")
+        if not final_answer:
+            final_answer = extract_tags(content, "report")
+        if not final_answer:
+            final_answer = content
+
+        tasks[0].output_str = final_answer
+        tasks[0].output_tokens = tasks[0].output_tokens or []
+
+
+def create_iter_research_controller(
+    max_tokens: int = 16384,
+    max_turn: int = 25,
+    max_format_retries: int = 5,
+    max_observation_length: int = 128000,
+    max_webpage_tokens: int = 48000,
+    max_tavily_search_chars: int = 6000,
+    enable_statistics: bool = False,
+    enable_tracing: bool = False,
+) -> Controller:
+    sampling_params = {
+        # "temperature": 0.6,
+        # "top_p": 0.95,
+        "max_tokens": max_tokens,
+    }
+
+    generation_controller = NativeGenerationController(sampling_params=sampling_params)
+    visit_controller = VisitController(
+        generation_controller=generation_controller,
+        max_webpage_tokens=max_webpage_tokens,
+    )
+    tavily_controller = TavilyController(
+        generation_controller=generation_controller,
+        compress_threshold_chars=max_tavily_search_chars,
+    )
+
+    controller_type = IterResearchController
+
+    if enable_statistics:
+
+        def wrap_with_profiler(cls, name):
+            return with_task_collection(
+                f"{name}TaskCollection",
+                TaskMetricsCollector,
+                controller_name=name,
+                task_types=[ChatTask, MCPCallTask],
+                enable_print=True,
+                capture_messages=True,
+            )(cls)
+
+        controller_type = wrap_with_profiler(controller_type, "IterResearch")
+
+    if enable_tracing:
+        controller_type = with_execution_tracing("IterResearch")(controller_type)
+        controller_type = tokenize_trace_scope()(controller_type)
+
+    return controller_type(
+        generation_controller=generation_controller,
+        visit_controller=visit_controller,
+        tavily_controller=tavily_controller,
+        max_turn=max_turn,
+        max_format_retries=max_format_retries,
+        max_observation_length=max_observation_length,
+    )
+
+
+def create_iter_research_scaffolding_llm(
+    generation_worker: Worker,
+    mcp_worker: Worker,
+    max_tokens: int = 16384,
+    max_turn: int = 25,
+    max_format_retries: int = 5,
+    max_observation_length: int = 128000,
+    max_webpage_tokens: int = 48000,
+    max_tavily_search_chars: int = 6000,
+    max_parallel_requests: int = 1024,
+    enable_statistics: bool = False,
+    enable_tracing: bool = False,
+) -> ScaffoldingLlm:
+    controller = create_iter_research_controller(
+        max_tokens=max_tokens,
+        max_turn=max_turn,
+        max_format_retries=max_format_retries,
+        max_observation_length=max_observation_length,
+        max_webpage_tokens=max_webpage_tokens,
+        max_tavily_search_chars=max_tavily_search_chars,
+        enable_statistics=enable_statistics,
+        enable_tracing=enable_tracing,
+    )
+
+    workers = {
+        NativeGenerationController.WorkerTag.GENERATION: generation_worker,
+        IterResearchController.WorkerTag.TOOL_CALL: mcp_worker,
+        VisitController.WorkerTag.TOOL_CALL: mcp_worker,
+        TavilyController.WorkerTag.TOOL_CALL: mcp_worker,
+        DropKVCacheWorkerTag.DROP_KV_CACHE: generation_worker,
+    }
+    if enable_tracing:
+        workers[TokenizeWorkerTag.TOKENIZE] = generation_worker
+
+    scaffolding_llm = ScaffoldingLlm(
+        controller,
+        workers,
+        max_parallel_requests=max_parallel_requests,
+    )
+
+    if enable_tracing:
+        scaffolding_llm.enable_output_task_collection()
+
+    return scaffolding_llm
diff --git a/tensorrt_llm/scaffolding/contrib/iter_research/prompts.py b/tensorrt_llm/scaffolding/contrib/iter_research/prompts.py
new file mode 100644
index 000000000000..63b1a6ac8abb
--- /dev/null
+++ b/tensorrt_llm/scaffolding/contrib/iter_research/prompts.py
@@ -0,0 +1,288 @@
+# ruff: noqa: E501
+
+from tensorrt_llm.scaffolding import system_prompt
+
+INITIAL_SYSTEM_PROMPT = system_prompt(
+    """You are a professional problem-solving agent with rigorous information verification capabilities and deep analytical thinking.
+
+## CRITICAL OUTPUT FORMAT REQUIREMENTS
+You MUST follow this exact format. Every response must contain:
+1. <report>...</report> (always required)
+2. Exactly one native tool call in the structured tool_calls field (always required)
+3. The tool call MUST NOT be written in the text body
+
+## Input Format
+- **Current Date**: Current Date
+- **Question**: The problem posed by the user that needs to be solved
+- **Available Tools**: The available tools are provided through the native tools field. A readable summary may also be included in the input.
+
+## Output Format
+
+<report>
+### Status Report and Deep Analysis
+**Problem Essence Analysis**: [Deeply analyze core elements, complexity levels, and potential pitfalls]
+**Problem-Solving Planning**: [Based on the depth of understanding of the original problem and confirmed key information, clarify what still needs to be confirmed, analyze information sufficiency and cognitive blind spots]
+</report>
+You MUST output this section enclosed with <report></report> tags!
+
+After the report, call exactly one tool using the native tool call mechanism supplied by the API.
+Do not include <tool_call> tags, JSON tool-call text, function-call markdown, or any other textual representation of the tool call in your message content.
+
+## Working Principles
+1. **Deep Thinking**: Pursue essential understanding, not satisfied with surface phenomena
+2. **Evidence-Driven**: Make reasoning decisions based on reliable evidence through deep thinking
+3. **You are required to maintain detailed documentation in all your reports and actions, providing sufficient information for others to fully grasp your progress and effectively continue or modify the research trajectory based on your contributions.**
+
+## Research Rigor Requirements
+- Before answering, build an explicit coverage checklist from the user's question. Track which required dimensions are covered, partially covered, or still missing.
+- Do not treat a search-result snippet as a fully verified source. Search results are for discovery and hypothesis formation; use Visit on key primary, official, peer-reviewed, or otherwise authoritative sources whenever possible.
+- For broad research, literature review, medical, financial, legal, scientific, or policy questions, one search call is normally insufficient. Continue gathering information unless the question is genuinely simple or the available evidence already covers all major dimensions.
+- If a Visit call fails, returns only raw PDF/binary text, returns a login/landing page, or lacks the requested evidence, record that limitation and try an alternate source or query before concluding.
+- Respect the Current Date. Do not rely on sources, events, reports, or studies dated after the Current Date unless the user explicitly asks for future or hypothetical information; if such material appears in search results, mark it unusable for factual verification.
+
+## Special Requirements
+- All tools in the tool list are real and functional - as long as you make correct tool calls, you will receive their returned results.
+- Clearly distinguish between "confirmed facts," "highly credible inferences," and "hypotheses to be verified"
+- Clearly indicate uncertainty when information is insufficient
+- Always focus on the original question
+- When outputting [Status Report and Deep Analysis], never omit key actions and results, even if these actions or results do not meet expectations, these conclusions must still be documented.
+
+## FORMAT REMINDER
+- The message content must start with a <report></report> section.
+- The message must also include exactly one native tool call in the structured tool_calls field.
+- Never write the tool call in the text body.
+""",
+    name="iter_research.initial_system_prompt",
+)
+
+INITIAL_INPUT_PROMPT = """## Input
+- Current Date: {date_to_use}
+- Question: {question}
+- Available Tools Summary (the actual callable tool schemas are provided separately through the native tools field)
+{tools}
+
+Now please begin your deep analytical work. The language of your output must be consistent with the language of the question. If the question is in Chinese, output in Chinese; if the question is in English, output in English.
+"""
+
+INSTRUCTION_SYSTEM_PROMPT = system_prompt(
+    """You are a professional problem-solving agent with rigorous information verification capabilities and deep analytical thinking.
+
+## CRITICAL OUTPUT FORMAT REQUIREMENTS
+You MUST follow this exact format. Every response must contain:
+1. <report>...</report> (always required)
+2. Either <answer>...</answer> in the message content OR exactly one native tool call in the structured tool_calls field (never both)
+3. Native tool calls MUST NOT be written in the message content
+
+## Input Format
+- **Current Date**: Current Date
+- **Question**: The problem posed by the user that needs to be solved
+- **Last Status Report and Deep Analysis**: A summary overview of current work progress
+- **Last Native Tool Call**: The specific structured action taken in the previous round, shown as controller-rendered JSON for context only
+- **Last Tool Message**: The results and feedback obtained after the previous action, provided as a separate tool-role message
+
+## Output Format
+
+<report>
+### Status Report and Deep Analysis
+**Progress Achieved:**
+[Based on the Last Status Report and Deep Analysis and the separate Last Tool Message provided in the input, compile a comprehensive and complete documentation of all currently collected information, conclusions, data, and findings. This section must capture ALL important information without any omissions, presented in plain text format with corresponding sources clearly annotated. You must directly record the actual information content rather than using referential markers or summaries. This includes:
+1. All factual data and evidence collected
+2. All analytical conclusions and insights derived
+3. All source materials and their verification status
+4. All uncertainties, limitations, or gaps identified
+5. Complete integration of previous progress with new findings
+The documentation must be sufficiently detailed and complete that someone can fully inherit and understand all achieved progress to seamlessly continue the research without losing any critical information or context.]
+
+**Next Steps Plan:**
+[Based on the comprehensive progress achieved above, formulate a detailed and actionable plan for the next phase of research or investigation.]
+</report>
+You MUST output this section enclosed with <report></report> tags!
+
+**Decision Point**: Are you certain that no further verification or information gathering is needed to provide the final answer?
+
+Before choosing YES, apply this **Final Answer Gate**:
+1. **Coverage**: Every major dimension in the original question is covered by evidence or explicitly marked as unavailable.
+2. **Source quality**: Key claims are supported by reliable sources. Search snippets alone are not enough for precise statistics, medical guidance, legal/financial recommendations, academic claims, or named case studies.
+3. **Failure handling**: If the last tool message contains "Failed to fetch", raw PDF/binary content, an unrelated page, or insufficient evidence, you should normally perform another search or Visit rather than answer.
+4. **Minimum depth for research tasks**: For broad research/report/literature-review questions, do not answer after only one information-gathering call unless the question is narrow and the evidence already covers all requested dimensions.
+5. **Date consistency**: Do not use sources dated after the Current Date as factual evidence unless explicitly allowed by the user.
+6. **Uncertainty discipline**: If evidence is incomplete, say so and continue gathering information when tools remain available.
+
+**If YES - Information is sufficient:**
+<answer>
+[Answer Format:
+1. **Language**: Your answer should be in the same language as the question. If the question uses English, answer in English. If the question uses Chinese, answer in Chinese.
+2. The answer should include as much relevant content as possible. Organize the content into separate paragraphs to avoid overly long sections. Avoid content duplication in the answer.
+3. Do not include any non-text elements such as URLs, images, or tables that appeared in the reasoning.
+4. Output only the answer text. Do not use any additional symbols or start with phrases like 'Here is my answer'.
+5. First, output a direct answer to the question.
+6. Do not just output the answer to the question; provide a rich and lengthy response by synthesizing all relevant information, and format it using markdown.
+7. For statistical data with at least 3 items, use a markdown table to present the results, ensuring the table description is clear. For less than 3 items, describe them directly in text.
+8. For research-type questions, try to generate a report of over 1000 words, using subheadings and other elements to improve readability and logic.]
+</answer>
+You MUST output this section enclosed with <answer></answer> tags!
+
+**If NO - Further action needed:**
+Call exactly one tool using the native tool call mechanism supplied by the API.
+Do not include <tool_call> tags, JSON tool-call text, function-call markdown, or any other textual representation of the tool call in your message content.
+
+## Working Principles
+1. **Rigorous Verification**: Critically evaluate all information sources
+2. **Deep Thinking**: Pursue essential understanding, not satisfied with surface phenomena
+3. **Evidence-Driven**: Make reasoning decisions based on reliable evidence through deep thinking
+4. **You are required to maintain detailed documentation in all your reports and actions, providing sufficient information for others to fully grasp your progress and effectively continue or modify the research trajectory based on your contributions.**
+
+## Research Rigor Requirements
+- Maintain a coverage checklist for the user's requested dimensions in every report.
+- Label source status explicitly: verified by visited source, search-snippet only, failed fetch, raw/unreadable content, or inference.
+- Prefer primary/official/peer-reviewed sources for core factual claims. Use secondary sources only when primary sources are unavailable and clearly note the limitation.
+- When evidence conflicts, investigate the conflict instead of choosing the most convenient result.
+- Never upgrade search-snippet-only information into "confirmed fact" without caveat.
+
+## Special Requirements
+- All tools in the tool list are real and functional - as long as you make correct tool calls, you will receive their returned results.
+- Clearly distinguish between "confirmed facts," "highly credible inferences," and "hypotheses to be verified"
+- Clearly indicate uncertainty when information is insufficient
+- Always focus on the original question
+- When outputting [Status Report and Deep Analysis], never omit key actions and results, even if these actions or results do not meet expectations, these conclusions must still be documented.
+- **When further action is needed, you must select an appropriate tool from your available tool list and carefully configure the tool call parameters based on the tool's specific characteristics and requirements**
+- **When the current status is sufficient to answer the question, must provide the final answer enclosed with <answer></answer> tags rather than continue with actions**
+
+## FORMAT REMINDER
+- Start with <report>...</report> section
+- Then choose: <answer>...</answer> in text if sufficient info, OR exactly one native tool call in the structured tool_calls field if more action is needed
+- Never output both an answer and a native tool call in the same response
+- Never write <tool_call> tags or tool-call JSON in the text body
+
+## Input
+- Current Date: {date_to_use}
+- Question: {question}
+- Available Tools Summary (the actual callable tool schemas are provided separately through the native tools field)
+{tools}
+""",
+    name="iter_research.instruction_system_prompt",
+)
+
+INSTRUCTION_INPUT_PROMPT = """- Last Status Report and Deep Analysis:
+<report>
+{report}
+</report>
+- Last Native Tool Call (controller-rendered JSON for context only; do not copy this format into your response):
+<last_tool_call>
+{action}
+</last_tool_call>
+- Last Tool Response:
+<tool_response>
+{observation}
+</tool_response>
+
+Now please begin your deep analytical work. The language of your output must be consistent with the language of the question. If the question is in Chinese, output in Chinese; if the question is in English, output in English.
+"""
+
+LAST_INSTRUCTION_SYSTEM_PROMPT = system_prompt(
+    """You are a professional problem-solving agent with rigorous information verification capabilities and deep analytical thinking.
+
+## CRITICAL OUTPUT FORMAT REQUIREMENTS
+You MUST follow this exact format. Every response must contain:
+1. <report>...</report> (always required)
+2. <answer>...</answer> (always required)
+
+## Input Format
+- **Current Date**: Current Date
+- **Question**: The problem posed by the user that needs to be solved
+- **Last Status Report and Deep Analysis**: A summary overview of current work progress
+- **Last Native Tool Call**: The specific structured action taken in the previous round, shown as controller-rendered JSON for context only
+- **Last Tool Message**: The results and feedback obtained after the previous action, provided as a separate tool-role message
+
+## Output Format
+
+<report>
+### Status Report and Deep Analysis
+**Progress Achieved:**
+[Based on the Last Status Report and Deep Analysis and the separate Last Tool Message provided in the input, compile a comprehensive and complete documentation of all currently collected information, conclusions, data, and findings. This section must capture ALL important information without any omissions, presented in plain text format with corresponding sources clearly annotated. You must directly record the actual information content rather than using referential markers or summaries. This includes:
+1. All factual data and evidence collected
+2. All analytical conclusions and insights derived
+3. All source materials and their verification status
+4. All uncertainties, limitations, or gaps identified
+5. Complete integration of previous progress with new findings
+The documentation must be sufficiently detailed and complete that someone can fully inherit and understand all achieved progress to seamlessly continue the research without losing any critical information or context.]
+</report>
+You MUST output this section enclosed with <report></report> tags!
+
+<answer>
+[Answer Format:
+1. **Language**: Your answer should be in the same language as the question. If the question uses English, answer in English. If the question uses Chinese, answer in Chinese.
+2. The answer should include as much relevant content as possible. Organize the content into separate paragraphs to avoid overly long sections. Avoid content duplication in the answer.
+3. Do not include any non-text elements such as URLs, images, or tables that appeared in the reasoning.
+4. Output only the answer text. Do not use any additional symbols or start with phrases like 'Here is my answer'.
+5. First, output a direct answer to the question.
+6. Do not just output the answer to the question; provide a rich and lengthy response by synthesizing all relevant information, and format it using markdown.
+7. For statistical data with at least 3 items, use a markdown table to present the results, ensuring the table description is clear. For less than 3 items, describe them directly in text.
+8. For research-type questions, try to generate a report of over 1000 words, using subheadings and other elements to improve readability and logic.]
+</answer>
+You MUST output this section enclosed with <answer></answer> tags!
+
+## Working Principles
+1. **Rigorous Verification**: Critically evaluate all information sources
+2. **Deep Thinking**: Pursue essential understanding, not satisfied with surface phenomena
+3. **Evidence-Driven**: Make reasoning decisions based on reliable evidence through deep thinking
+
+## Final-Round Evidence Discipline
+- You must give a final answer because this is the last round, but do not hide evidence gaps.
+- Clearly separate verified findings from search-snippet-only information and unsupported hypotheses.
+- If key Visit attempts failed or returned unreadable content, state that limitation in the report and avoid presenting unsupported claims as confirmed.
+- Do not use sources dated after the Current Date as factual evidence unless the user explicitly permits future information.
+
+## Special Requirements
+- Clearly distinguish between "confirmed facts," "highly credible inferences," and "hypotheses to be verified"
+- Clearly indicate uncertainty when information is insufficient
+- Always focus on the original question
+- When outputting [Status Report and Deep Analysis], never omit key actions and results, even if these actions or results do not meet expectations, these conclusions must still be documented.
+
+## FORMAT REMINDER
+- Start with <report>...</report> section
+- Then <answer>...</answer> section
+- you MUST give a final response
+
+## Input
+- Current Date: {date_to_use}
+- Question: {question}
+""",
+    name="iter_research.last_instruction_system_prompt",
+)
+
+LAST_INSTRUCTION_INPUT_PROMPT = """- Last Status Report and Deep Analysis:
+<report>
+{report}
+</report>
+- Last Native Tool Call (controller-rendered JSON for context only; do not copy this format into your response):
+<last_tool_call>
+{action}
+</last_tool_call>
+- Last Tool Response:
+<tool_response>
+{observation}
+</tool_response>
+
+Now please begin your deep analytical work. The language of your output must be consistent with the language of the question. If the question is in Chinese, output in Chinese; if the question is in English, output in English.
+"""
+
+OBSERVATION_PROMPT = """**Tool results**:
+{tool_response}"""
+
+VISIT_EXTRACTOR_PROMPT = """Please process the following webpage content and user goal to extract relevant information:
+
+## **Webpage Content**
+{webpage_content}
+
+## **User Goal**
+{goal}
+
+## **Task Guidelines**
+1. **Content Scanning for Rational**: Locate the **specific sections/data** directly related to the user's goal within the webpage content
+2. **Key Extraction for Evidence**: Identify and extract the **most relevant information** from the content, you never miss any important information, output the **full original context** of the content as far as possible, it can be more than three paragraphs.
+3. **Summary Output for Summary**: Organize into a concise paragraph with logical flow, prioritizing clarity and judge the contribution of the information to the goal.
+4. **Failure Detection**: If the content says "Failed to fetch", is mostly raw PDF/binary data, is a login/landing page, or does not contain evidence relevant to the goal, set "evidence" to an empty list or only the exact failure text, and clearly state that no usable evidence was extracted. Do not infer facts from inaccessible or unreadable content.
+
+**Final Output Format using JSON format has "rational", "evidence", "summary" fields**
+"""
diff --git a/tensorrt_llm/scaffolding/contrib/iter_research/utils.py b/tensorrt_llm/scaffolding/contrib/iter_research/utils.py
new file mode 100644
index 000000000000..6d945584325c
--- /dev/null
+++ b/tensorrt_llm/scaffolding/contrib/iter_research/utils.py
@@ -0,0 +1,127 @@
+import json
+import random
+import re
+from datetime import datetime, timedelta
+
+from tensorrt_llm.scaffolding.task import AssistantMessage, OpenAIToolDescription
+
+TOOLS = [
+    OpenAIToolDescription(
+        name="tavily_search",
+        description=(
+            "Perform web searches via Tavily then returns a string of the top "
+            "search results. Accepts multiple queries."
+        ),
+        parameters={
+            "query": {
+                "type": "array",
+                "items": {"type": "string", "description": "The search query."},
+                "minItems": 1,
+                "description": "The list of search queries.",
+            }
+        },
+    ),
+    OpenAIToolDescription(
+        name="Visit",
+        description="Visit webpage(s) or paper(s) and return the summary of the content.",
+        parameters={
+            "url": {
+                "type": "array",
+                "items": {"type": "string"},
+                "minItems": 1,
+                "description": "The URL(s) of the webpage(s) or paper(s) to visit.",
+            },
+            "goal": {
+                "type": "string",
+                "description": "The goal of the visit for webpage(s) or paper(s).",
+            },
+            "parse_type": {
+                "type": "string",
+                "enum": ["html", "pdf"],
+                "default": "html",
+                "description": "Specify whether to visit a HTML webpage or a PDF paper.",
+            },
+        },
+    ),
+    OpenAIToolDescription(
+        name="PythonInterpreter",
+        description=(
+            "Executes arbitrary Python code in a secure, sandboxed environment. This "
+            "tool is designed for performing complex calculations, data manipulations, "
+            "string processing, logical operations, and general programming tasks. Use "
+            "print() for any output you want to see. The environment only has basic "
+            "packages by default; before importing a non-basic package, you may first "
+            "call this tool to install it, for example: import subprocess, sys; "
+            "subprocess.check_call([sys.executable, '-m', 'pip', 'install', '<package>'])."
+        ),
+        parameters={
+            "code": {
+                "type": "string",
+                "description": (
+                    "The Python code to execute. All output should be explicitly "
+                    "printed using print() functions."
+                ),
+            }
+        },
+    ),
+]
+
+
+def extract_tags(text: str, tag: str) -> str:
+    pattern = r"<{TAG}>(.*?)</{TAG}>".format(TAG=tag)
+    match = re.search(pattern, text, re.DOTALL)
+    if match:
+        return match.group(1).strip()
+    return ""
+
+
+def check_report_action(
+    message: AssistantMessage,
+    require_tool_call: bool = False,
+    allow_tool_call: bool = True,
+    allow_tool_call_without_report: bool = False,
+) -> tuple:
+    content = message.content or ""
+    report = extract_tags(content, "report")
+    text_action = extract_tags(content, "tool_call")
+    answer = extract_tags(content, "answer")
+    tool_calls = message.tool_calls or []
+
+    if text_action:
+        return False, "Tool call must use the native tool_calls field, not text tags!"
+    if answer and tool_calls:
+        return False, "Both answer and tool call found!"
+    if len(tool_calls) > 1:
+        return False, "Expected at most one tool call!"
+    if require_tool_call and len(tool_calls) != 1:
+        return False, "Expected exactly one tool call!"
+    if tool_calls and not allow_tool_call:
+        return False, "Tool call is not allowed in the final response!"
+    if not report:
+        if not (allow_tool_call_without_report and tool_calls and not answer):
+            return False, "Report not found!"
+    if not tool_calls and not answer:
+        return False, "Neither answer nor tool call found!"
+
+    return True, "success"
+
+
+def random_date(start=None, end=None) -> str:
+    if start is None:
+        start = datetime(2023, 1, 1)
+    if end is None:
+        end = datetime(2025, 12, 31)
+    delta = end - start
+    random_days = random.randint(0, delta.days)
+    final_date = start + timedelta(days=random_days)
+    return final_date.strftime("%Y-%m-%d")
+
+
+def get_tool_definitions() -> str:
+    return json.dumps([tool.to_dict()["function"] for tool in TOOLS], indent=2)
+
+
+def truncate_text(text: str, max_length: int) -> str:
+    if len(text) > max_length:
+        return text[:max_length]
+    return text
diff --git a/tensorrt_llm/scaffolding/contrib/open_deep_research/README.md b/tensorrt_llm/scaffolding/contrib/open_deep_research/README.md
index 9bb2cc6c886d..90cf590c2425 100644
--- a/tensorrt_llm/scaffolding/contrib/open_deep_research/README.md
+++ b/tensorrt_llm/scaffolding/contrib/open_deep_research/README.md
@@ -1,105 +1,119 @@
 # Open Deep Research
 
-This module implements Open Deep Research with Scaffolding to enable joint optimization between multi-agent applications and TensorRT-LLM.
+Open Deep Research agent built on TensorRT-LLM Scaffolding. It uses the same MCP stack as IterResearch (Tavily, Google Scholar, webpage fetch, Python sandbox via `coder_mcp`), while preserving a Planner-Executor multi-agent design.
 
 ## Design Overview
 
-**Open Deep Research** is an open-source deep research agent built on a multi-agent Planner-Executor architecture:
+**Open Deep Research** follows a Planner-Executor architecture:
 
-- **Supervisor (Planner)**: Accepts user input, generates a research brief, delegates tasks to Researchers, and synthesizes the final report once sufficient information has been gathered.
-- **Researcher (Executor)**: Receives a research topic, conducts multiple rounds of interaction with external search tools, then summarizes and compresses the findings before returning results.
+- **Supervisor (Planner)**: Accepts user input, generates a research brief, delegates tasks to Researchers, and synthesizes the final report.
+- **Researcher (Executor)**: Receives a topic, performs multiple rounds of tool-augmented research, then summarizes and compresses findings.
 
-### Architecture
+### Frontend (Control Flow)
 
-The frontend-backend decoupling and modular architecture of Scaffolding supports building multi-agent systems efficiently.
-
-#### Frontend (Control Flow)
-
-The frontend encompasses the control flow of the Planner-Executor architecture through `Controller`s:
+Controllers orchestrate the workflow:
 
 | Controller | Description |
 |------------|-------------|
-| `Supervisor` | Entry controller for the entire agent; orchestrates the research workflow |
+| `Supervisor` | Entry controller for the workflow |
 | `BriefController` | Generates the research brief from user input |
-| `ResearchPlanningController` | Plans and delegates research topics to sub-agents |
-| `Researcher` | Sub-agent that conducts research on specific topics |
-| `ChatWithMCPController` | Handles tool calling for web search (reusable Scaffolding controller) |
-| `Compressor` | Compresses search results and model reflections |
-| `FinalReportController` | Synthesizes findings into the final report |
+| `ResearchPlanningController` | Plans and delegates topics to sub-agents |
+| `Researcher` | Sub-agent that researches assigned topics |
+| `ChatWithMCPController` | Handles MCP-based tool calling |
+| `Compressor` | Compresses search outputs and reflections |
+| `FinalReportController` | Synthesizes the final report |
 
-#### Backend (Workers)
+### Backend (Workers)
 
-The backend serves LLM generation and tool call requests through `Worker` instances:
+Workers serve generation and tool requests:
 
 | Worker | Description |
 |--------|-------------|
-| `TRTOpenaiWorker` | Serves LLM generation requests via TensorRT-LLM OpenAI-compatible endpoint |
-| `MCPWorker` | Serves tool calling requests via MCP server |
+| `TRTOpenaiWorker` | LLM generation via TensorRT-LLM OpenAI-compatible endpoint |
+| `MCPWorker` | MCP tool calling |
 
 ### Modularity
 
-Scaffolding supports the evolution of individual components independent of other components in the multi-agent system. For example:
-- To use a more sophisticated sub-agent for the final report, simply replace the corresponding Controller in that module.
-- To support other LLM endpoints (e.g., Anthropic, Google), implement a Worker similar to `TRTOpenaiWorker`.
+Each controller/worker can evolve independently. For example:
+
+- Swap in a different report-synthesis controller without changing the rest of the pipeline.
+- Add another model endpoint by implementing a worker similar to `TRTOpenaiWorker`.
+
+## Prerequisites
 
-## Quick Start
+1. Serve a chat model at an OpenAI-compatible `base_url` (for example, `trtllm-serve`).
+2. If code execution is needed, start `coder_mcp.py` (Apiary-backed), then MCP servers.
+3. Start each MCP server with the same config — the shared example is `examples/scaffolding/contrib/open_deep_research/config.example.yaml` (copy it to your own `config.yaml` and fill in the keys).
+4. Fill required API keys in `config.yaml` (Tavily, Jina/Scraper for fetch, Google Scholar credentials, and so on).
 
-### 1. Start TensorRT-LLM Server
+Example MCP startup commands:
 
 ```bash
-trtllm-serve serve Qwen3/Qwen3-30B-A3B \
-    --max_num_tokens 32768 \
-    --kv_cache_free_gpu_memory_fraction 0.8 \
-    --extra_llm_api_options .extra-llm-api-config.yml \
-    --reasoning_parser qwen3 \
-    --tool_parser qwen3
+cd examples/scaffolding/mcp/tavily_search && uv run tavily_search.py \
+    --config examples/scaffolding/contrib/open_deep_research/config.example.yaml
 ```
 
-Create `.extra-llm-api-config.yml` with the following content:
-
-```yaml
-reorder_policy_config:
-    policy_name: "AgentTree"
-    policy_args:
-        agent_percentage: 0.5
-        agent_types: ["agent_deep_research"]
-        agent_inflight_seq_num: 8
+```bash
+cd examples/scaffolding/mcp/google_scholar && uv run google_scholar.py \
+    --config examples/scaffolding/contrib/open_deep_research/config.example.yaml
 ```
 
-### 2. Start Tavily MCP Server
+```bash
+cd examples/scaffolding/mcp/fetch_webpage && uv run fetch_webpage.py \
+    --config examples/scaffolding/contrib/open_deep_research/config.example.yaml
+```
 
 ```bash
-cd examples/scaffolding/contrib/open_deep_research/TavilyMCP
-export TAVILY_API_KEY=<your_api_key>
-uv run travily.py
+python examples/scaffolding/mcp/coder/coder_mcp.py \
+    --apiary-url http://172.17.0.1:8080 \
+    --default-image python:3.12-slim \
+    --port 8086
 ```
 
-### 3. Run the Example
+## Single Prompt Run
+
+Use the runnable example entrypoint:
 
 ```bash
-cd examples/scaffolding/contrib/open_deep_research
-python run_deep_research.py
+python examples/scaffolding/contrib/open_deep_research/run_open_deep_research.py \
+  --config examples/scaffolding/contrib/open_deep_research/config.example.yaml \
+  --base_url http://localhost:8000/v1 \
+  --model Qwen3/Qwen3-30B-A3B \
+  --enable_tracing
 ```
 
-#### Optional Flags
+You can override `--prompt` for custom questions. Add `--enable_tracing` or `--enable_query_collector` as needed. When both CLI flags and config file values are set, CLI flags take precedence.
 
-- `--enable_statistics`: Enable token counting and task timing metrics
-- `--enable_query_collector`: Enable query collection for debugging
-- `--base_url`: Specify a custom TensorRT-LLM server URL (default: `http://localhost:8000/v1`)
-- `--model`: Specify a different model (default: `Qwen3/Qwen3-30B-A3B`)
+## Tracing (`--enable_tracing`)
 
-Example with statistics enabled:
+`--enable_tracing` captures execution traces for a single run.
 
-```bash
-python run_deep_research.py --enable_statistics
-```
+### Output directory behavior
+
+- If `--trace_output_dir` is set, traces are written there.
+- Otherwise, a timestamped directory is created: `open_deep_research_trace_<YYYYMMDD_HHMMSS>`.
+- The chosen output directory is printed during execution.
 
-To enable sub-request marking for detailed tracing:
+### Trace files
+
+- `open_deep_research.trace.json`: compact trace for replay/analysis.
+- `open_deep_research.full.trace.json`: full trace with complete payloads.
+
+### Example with explicit trace directory
 
 ```bash
-ENABLE_SUB_REQUEST_MARKER=1 python run_deep_research.py --enable_statistics
+python examples/scaffolding/contrib/open_deep_research/run_open_deep_research.py \
+  --config examples/scaffolding/contrib/open_deep_research/config.example.yaml \
+  --base_url http://localhost:8000/v1 \
+  --model Qwen3/Qwen3-30B-A3B \
+  --enable_tracing \
+  --trace_output_dir ./open_deep_research_trace_manual
 ```
 
+## Trace Replay
+
+For replaying traces, use `run_deep_research_replay.py` in the example directory, or the general replay tooling under `examples/scaffolding/trace_replay`.
+
 ## Acknowledgments
 
 This implementation follows the design of [Open Deep Research](https://github.com/langchain-ai/open_deep_research) by LangChain.
diff --git a/tensorrt_llm/scaffolding/contrib/open_deep_research/prompts.py b/tensorrt_llm/scaffolding/contrib/open_deep_research/prompts.py
index 4d2855811aec..91872733b121 100644
--- a/tensorrt_llm/scaffolding/contrib/open_deep_research/prompts.py
+++ b/tensorrt_llm/scaffolding/contrib/open_deep_research/prompts.py
@@ -1,12 +1,10 @@
 # ruff: noqa: E501
 
-generate_research_brief_prompt = """You will be given a set of messages that have been exchanged so far between yourself and the user.
-Your job is to translate these messages into a more detailed and concrete research question that will be used to guide the research.
+from tensorrt_llm.scaffolding import system_prompt
 
-The messages that have been exchanged so far between yourself and the user are:
-<Messages>
-{messages}
-</Messages>
+GENERATE_RESEARCH_BRIEF_SYSTEM_PROMPT = system_prompt(
+    """You will be given a set of messages that have been exchanged so far between yourself and the user.
+Your job is to translate these messages into a more detailed and concrete research question that will be used to guide the research.
 
 Today's date is {date}.
 
@@ -33,15 +31,19 @@
 - For academic or scientific queries, prefer linking directly to the original paper or official journal publication rather than survey papers or secondary summaries.
 - For people, try linking directly to their LinkedIn profile, or their personal website if they have one.
 - If the query is in a specific language, prioritize sources published in that language.
-"""
-
-generate_research_brief_prompt_prefix = """You will be given a set of messages that have been exchanged so far between yourself and the user.
-Your job is to translate these messages into a more detailed and concrete research question that will be used to guide the research.
+""",
+    name="open_deep_research.generate_research_brief_system_prompt",
+)
 
-The messages that have been exchanged so far between yourself and the user are:
+GENERATE_RESEARCH_BRIEF_USER_PROMPT = """The messages that have been exchanged so far between yourself and the user are:
+<Messages>
+{messages}
+</Messages>
 """
 
-supervisor_system_prompt = """You are a research supervisor. Your job is to conduct research by calling the "conduct_research" tool. For context, today's date is {date}.
+
+SUPERVISOR_SYSTEM_PROMPT = system_prompt(
+    """You are a research supervisor. Your job is to conduct research by calling the "conduct_research" tool. For context, today's date is {date}.
 
 <Task>
 Your focus is to call the "conduct_research" tool to conduct research against the overall research question passed in by the user.
@@ -107,11 +109,13 @@
 - A separate agent will write the final report - you just need to gather information
 - When calling conduct_research, provide complete standalone instructions - sub-agents can't see other agents' work
 - Do NOT use acronyms or abbreviations in your research questions, be very clear and specific
-</Scaling Rules>"""
+</Scaling Rules>""",
+    name="open_deep_research.supervisor_system_prompt",
+)
 
-supervisor_system_prompt_prefix = supervisor_system_prompt
 
-research_system_prompt = """You are a research assistant conducting research on the user's input topic. For context, today's date is {date}.
+RESEARCHER_SYSTEM_PROMPT = system_prompt(
+    """You are a research assistant conducting research on the user's input topic. For context, today's date is {date}.
 
 <Task>
 Your job is to use tools to gather information about the user's input topic.
@@ -119,47 +123,52 @@
 </Task>
 
 <Available Tools>
-You have access to two main tools:
-1. **web_search**: For conducting web searches to gather information
-2. **reflection**: For reflection and strategic planning during research
+You have access to four tools (three information-gathering tools plus reflection):
+
+1. **tavily_search**: General web search via Tavily. Pass `query` as a list of one or more strings.
+2. **fetch_webpage**: Fetch page or PDF text from specific URLs. Pass `url` as a list of strings; set `parse_type` to `"html"` or `"pdf"` as appropriate.
+3. **python_interpreter**: Run Python in the sandbox for computation, parsing, or verification. Pass `code` as a string; use `print()` for visible output. The environment only has basic packages by default. If you need a non-basic package, call python_interpreter before importing it with code like `import subprocess, sys; subprocess.check_call([sys.executable, "-m", "pip", "install", "<package>"])`, then import the package in a later python_interpreter call.
+4. **reflection**: Strategic reflection and planning (no external calls).
 
-**CRITICAL: Use reflection after each search to reflect on results and plan next steps. Do not call reflection with the web_search or any other tools. It should be to reflect on the results of the search.**
+**CRITICAL: Call reflection only by itself** (not in parallel with tavily_search, fetch_webpage, or python_interpreter). After you finish a batch of information-gathering tool calls, use reflection to decide what to do next.
 </Available Tools>
 
 <Instructions>
 Think like a human researcher with limited time. Follow these steps:
 
 1. **Read the question carefully** - What specific information does the user need?
-2. **Start with broader searches** - Use broad, comprehensive queries first
-3. **After each search, pause and assess** - Do I have enough to answer? What's still missing?
-4. **Execute narrower searches as you gather information** - Fill in the gaps
-5. **Stop when you can answer confidently** - Don't keep searching for perfection
+2. **Choose the right tools** - Prefer web search for discovery, including papers; use fetch_webpage when you already have URLs; use python_interpreter for non-trivial calculation or structured extraction.
+3. **Start broad, then narrow** - Use broad queries first, then targeted searches or direct fetches.
+4. **After each wave of tool calls, pause** - Use reflection: Do I have enough? What's missing?
+5. **Stop when you can answer confidently** - Don't keep gathering information for perfection.
 </Instructions>
 
 <Hard Limits>
-**Tool Call Budgets** (Prevent excessive searching):
-- **Simple queries**: Use 2-3 search tool calls maximum
-- **Complex queries**: Use up to 5 search tool calls maximum
-- **Always stop**: After 5 search tool calls if you cannot find the right sources
+**Tool Call Budgets** (Prevent excessive use):
+- **Simple queries**: Use roughly 2-4 information-gathering tool calls total when possible
+- **Complex queries**: Use up to about 8 information-gathering tool calls
+- **Always stop**: After about 8 information-gathering tool calls if you still cannot find the right sources
 
 **Stop Immediately When**:
 - You can answer the user's question comprehensively
-- You have 3+ relevant examples/sources for the question
-- Your last 2 searches returned similar information
+- You have several relevant sources or facts for the question
+- Your last rounds of gathering returned overlapping information
 </Hard Limits>
 
 <Show Your Thinking>
-After each tavily_search call, use reflection to analyze the results:
+After each wave of tavily_search / fetch_webpage / python_interpreter calls, use reflection to analyze the results:
 - What key information did I find?
 - What's missing?
 - Do I have enough to answer the question comprehensively?
-- Should I search more or provide my answer?
+- Should I gather more or stop?
 </Show Your Thinking>
-"""
+""",
+    name="open_deep_research.researcher_system_prompt",
+)
 
-research_system_prompt_prefix = research_system_prompt
 
-compress_system_prompt = """You are a research assistant that has conducted research on a topic by calling several tools and web searches. Your job is now to clean up the findings, but preserve all of the relevant statements and information that the researcher has gathered. For context, today's date is {date}.
+COMPRESSOR_SYSTEM_PROMPT = system_prompt(
+    """You are a research assistant that has conducted research on a topic by calling several tools and web searches. Your job is now to clean up the findings, but preserve all of the relevant statements and information that the researcher has gathered. For context, today's date is {date}.
 
 <Task>
 You need to clean up information gathered from tool calls and web searches in the existing messages.
@@ -195,36 +204,17 @@
 </Citation Rules>
 
 Critical Reminder: It is extremely important that any information that is even remotely relevant to the user's research topic is preserved verbatim (e.g. don't rewrite it, don't summarize it, don't paraphrase it).
-"""
-
-compress_system_prompt_prefix = compress_system_prompt
-
-compress_research_simple_human_prompt = """All above messages are about research conducted by an AI Researcher. Please clean up these findings.
-
-DO NOT summarize the information. I want the raw information returned, just in a cleaner format. Make sure all relevant information is preserved - you can rewrite findings verbatim."""
+""",
+    name="open_deep_research.compressor_system_prompt",
+)
 
-compress_research_simple_human_prompt_prefix = compress_research_simple_human_prompt
 
-final_report_generation_prompt = """Based on all the research conducted, create a comprehensive, well-structured answer to the overall research brief:
-<Research Brief>
-{research_brief}
-</Research Brief>
+FINAL_REPORT_GENERATION_PROMPT = """Based on all the research conducted, create a comprehensive, well-structured answer to the original research brief.
 
-For more context, here is all of the messages so far. Focus on the research brief above, but consider these messages as well for more context.
-<Messages>
-{messages}
-</Messages>
 CRITICAL: Make sure the answer is written in the same language as the human messages!
 For example, if the user's messages are in English, then MAKE SURE you write your response in English. If the user's messages are in Chinese, then MAKE SURE you write your entire response in Chinese.
 This is critical. The user will only understand the answer if it is written in the same language as their input message.
 
-Today's date is {date}.
-
-Here are the findings from the research that you conducted:
-<Findings>
-{findings}
-</Findings>
-
 Please create a detailed answer to the overall research brief that:
 1. Is well-organized with proper headings (# for title, ## for sections, ### for subsections)
 2. Includes specific facts and insights from the research
@@ -285,7 +275,7 @@
   [2] Source Title: URL
 - Citations are extremely important. Make sure to include these, and pay a lot of attention to getting these right. Users will often use these citations to look into more information.
 </Citation Rules>
-"""
 
-final_report_generation_prompt_prefix = """Based on all the research conducted, create a comprehensive, well-structured answer to the overall research brief:
+Today's date is {date}.
+
 """
diff --git a/tensorrt_llm/scaffolding/contrib/open_deep_research/researcher.py b/tensorrt_llm/scaffolding/contrib/open_deep_research/researcher.py
index 82054b9fe359..d84430e447f6 100644
--- a/tensorrt_llm/scaffolding/contrib/open_deep_research/researcher.py
+++ b/tensorrt_llm/scaffolding/contrib/open_deep_research/researcher.py
@@ -1,35 +1,59 @@
-import logging
+# Copyright (c) 2026, NVIDIA CORPORATION. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import json
 from dataclasses import dataclass, field
-from typing import List
+from typing import Any, List
 
+from examples.scaffolding.mcp.fetch_webpage import VisitController, VisitTask
+from examples.scaffolding.mcp.tavily_search import TavilyController, TavilyTask
+from tensorrt_llm.logger import logger
 from tensorrt_llm.scaffolding import (
     AssistantMessage,
     ChatTask,
     Controller,
+    MCPCallTask,
     SystemMessage,
     Task,
     UserMessage,
 )
-from tensorrt_llm.scaffolding.task_collection import drop_kv_cache_scope, sub_request_node
+from tensorrt_llm.scaffolding.controller import ChatWithMCPController
+from tensorrt_llm.scaffolding.task import ToolMessage
+from tensorrt_llm.scaffolding.task_collection import sub_request_node
 
-from .prompts import research_system_prompt, research_system_prompt_prefix
-from .tools import reflection_tool, web_search_tool
+from .prompts import RESEARCHER_SYSTEM_PROMPT
+from .tools import (
+    fetch_webpage_tool,
+    # google_scholar_tool,
+    python_interpreter_tool,
+    reflection_tool,
+    tavily_search_tool,
+)
 from .utils import get_today_str
 
-LOGGER = logging.getLogger()
-
 
 @dataclass
 class ResearchTask(Task):
     research_topic: str = field(default=None)
     research_result: str = field(default=None)
+    tool_call_id: str = field(default=None)
 
     @staticmethod
-    def from_topic(topic: str) -> "ResearchTask":
-        task = ResearchTask()
-        task.research_topic = topic
-        task.research_result = ""
-        return task
+    def from_topic(topic: str, tool_call_id: str) -> "ResearchTask":
+        return ResearchTask(research_topic=topic, research_result="", tool_call_id=tool_call_id)
 
 
 class Compressor(Controller):
@@ -71,10 +95,167 @@ def process(self, tasks: List[Task], **kwargs):
         return
 
 
+def _extraction_goal_from_chat(chat_task: ChatTask) -> str:
+    """Goal string for webpage extraction (matches IterResearch ``Visit`` goal)."""
+    for message in chat_task.messages:
+        if message.role == "user" and getattr(message, "content", None):
+            return str(message.content)
+    return "Extract relevant information for the research task."
+
+
+def _parse_tool_arguments(arguments: Any) -> dict:
+    if isinstance(arguments, dict):
+        return arguments
+    if isinstance(arguments, str):
+        return json.loads(arguments)
+    raise TypeError(f"Unsupported tool arguments type: {type(arguments).__name__}")
+
+
+class ResearchChatWithMCPController(ChatWithMCPController):
+    """Dispatches large retrieval tools through compression controllers.
+
+    ``fetch_webpage`` uses :class:`VisitController` for fetch + LLM summary.
+    ``tavily_search`` uses :class:`TavilyController` for search + optional LLM summary.
+    Other MCP tools keep the same batching behavior as :class:`ChatWithMCPController`.
+    """
+
+    def __init__(
+        self,
+        generation_controller: Controller,
+        visit_controller: VisitController,
+        tavily_controller: TavilyController,
+        system_prompts: Any = None,
+        max_iterations: int = 3,
+        tools: Any = None,
+    ):
+        super().__init__(
+            generation_controller=generation_controller,
+            system_prompts=system_prompts,
+            max_iterations=max_iterations,
+            tools=tools,
+        )
+        self.visit_controller = visit_controller
+        self.tavily_controller = tavily_controller
+
+    def clone(self) -> ResearchChatWithMCPController:
+        return ResearchChatWithMCPController(
+            generation_controller=self.generation_controller.clone(),
+            visit_controller=self.visit_controller.clone(),
+            tavily_controller=self.tavily_controller.clone(),
+            system_prompts=self.system_prompts,
+            max_iterations=self.max_iterations,
+            tools=self.tools,
+        )
+
+    def process(self, tasks: List[Task], **kwargs):
+        assert len(tasks) == 1, "ResearchChatWithMCPController only supports one task"
+        chat_task = tasks[0]
+        assert isinstance(chat_task, ChatTask), (
+            "ResearchChatWithMCPController only supports ChatTask"
+        )
+        goal = _extraction_goal_from_chat(chat_task)
+
+        for _ in range(self.max_iterations):
+            yield from self.generation_controller.process([chat_task])
+            response_message = chat_task.messages[-1]
+            if not isinstance(response_message, AssistantMessage):
+                logger.warning(
+                    "Stopping ChatWithMCP tool loop: expected AssistantMessage "
+                    "after generation, got %s",
+                    type(response_message).__name__,
+                )
+                break
+            if response_message.tool_calls:
+                tool_calls = response_message.tool_calls
+
+                tool_results = {}
+                mcp_tasks = []
+                mcp_indices = []
+                for i, tool_call in enumerate(tool_calls):
+                    if tool_call.function.name in ("fetch_webpage", "tavily_search"):
+                        continue
+                    mcp_tasks.append(
+                        MCPCallTask.create_mcptask(
+                            tool_call.id,
+                            tool_call.function.name,
+                            tool_call.function.arguments,
+                            self.WorkerTag.TOOLCALL,
+                        )
+                    )
+                    mcp_indices.append(i)
+
+                if mcp_tasks:
+                    yield mcp_tasks
+                for i, mcp_task in zip(mcp_indices, mcp_tasks):
+                    if mcp_task.result_str is None:
+                        continue
+                    tool_results[i] = (
+                        mcp_task.result_str,
+                        mcp_task.result_stdout,
+                        mcp_task.result_stderr,
+                    )
+
+                for i, tool_call in enumerate(tool_calls):
+                    tool_name = tool_call.function.name
+                    if tool_name == "fetch_webpage":
+                        args = _parse_tool_arguments(tool_call.function.arguments)
+                        urls = args.get("url", [])
+                        if isinstance(urls, str):
+                            urls = [urls]
+                        visit_task = VisitTask(
+                            urls=urls or [],
+                            goal=goal,
+                            parse_type=args.get("parse_type", "html"),
+                        )
+                        yield from self.visit_controller.process([visit_task])
+                        if visit_task.result_str is not None:
+                            tool_results[i] = (visit_task.result_str, None, None)
+                    elif tool_name == "tavily_search":
+                        args = _parse_tool_arguments(tool_call.function.arguments)
+                        queries = args.get("query", [])
+                        if isinstance(queries, str):
+                            queries = [queries]
+                        tavily_task = TavilyTask(query=queries or [], goal=goal)
+                        yield from self.tavily_controller.process([tavily_task])
+                        if tavily_task.result_str is not None:
+                            tool_results[i] = (
+                                tavily_task.result_str,
+                                tavily_task.result_stdout,
+                                tavily_task.result_stderr,
+                            )
+
+                for i, tool_call in enumerate(tool_calls):
+                    if i in tool_results:
+                        body, out, err = tool_results[i]
+                    else:
+                        # The MCP / visit / tavily controller failed to write
+                        # ``result_str`` (e.g., upstream 504, connection reset,
+                        # JSON parse error). Bedrock / Anthropic require every
+                        # tool_use_id in the prior assistant message to have a
+                        # matching tool_result in the immediately following
+                        # message; emit a placeholder so the request payload
+                        # stays valid and the loop can keep making progress.
+                        body = f"[{tool_call.function.name}] tool produced no result"
+                        out, err = None, None
+                    chat_task.add_message(
+                        ToolMessage(body, tool_call.id, trace_stdout=out, trace_stderr=err)
+                    )
+                if any(tc.function.name == "complete_task" for tc in tool_calls):
+                    break
+            else:
+                break
+
+
 @sub_request_node("Researcher")
-@drop_kv_cache_scope()
+# @drop_kv_cache_scope()
 class Researcher(Controller):
-    tools = [web_search_tool, reflection_tool]
+    tools = [
+        tavily_search_tool,
+        # google_scholar_tool,
+        fetch_webpage_tool,
+        python_interpreter_tool,
+        reflection_tool,
+    ]
 
     def __init__(self, chat_with_tools_controller: Controller, compress_controller: Controller):
         super().__init__()
@@ -88,12 +269,17 @@ def clone(self):
         )
 
     def process(self, research_tasks: List[ResearchTask], **kwargs):
+        assert len(research_tasks) == 1, "Researcher only supports one ResearchTask"
+        assert research_tasks[0].research_topic is not None, (
+            "ResearchTask must have a research topic"
+        )
+        assert research_tasks[0].tool_call_id is not None, "ResearchTask must have a tool call id"
+
         chat_task = ChatTask.create_from_prompt(
             research_tasks[0].research_topic,
             [
                 SystemMessage(
-                    research_system_prompt.format(date=get_today_str()),
-                    prefix=research_system_prompt_prefix,
+                    RESEARCHER_SYSTEM_PROMPT.format(date=get_today_str()),
                 )
             ],
             tools=self.tools,
@@ -103,5 +289,5 @@ def process(self, research_tasks: List[ResearchTask], **kwargs):
 
         yield from self.compress_controller.process([chat_task])
 
-        research_tasks[0].research_result = chat_task.output_str
+        research_tasks[0].research_findings = chat_task.output_str
         return
diff --git a/tensorrt_llm/scaffolding/contrib/open_deep_research/supervisor.py b/tensorrt_llm/scaffolding/contrib/open_deep_research/supervisor.py
index 1d499f2deecc..da7b2132a807 100644
--- a/tensorrt_llm/scaffolding/contrib/open_deep_research/supervisor.py
+++ b/tensorrt_llm/scaffolding/contrib/open_deep_research/supervisor.py
@@ -1,8 +1,23 @@
+# Copyright (c) 2026, NVIDIA CORPORATION. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 import copy
 import json
-from dataclasses import dataclass, field
 from typing import List
 
+from examples.scaffolding.mcp.fetch_webpage import VisitController
+from examples.scaffolding.mcp.tavily_search import TavilyController
 from tensorrt_llm.scaffolding.controller import (
     ChatWithMCPController,
     Controller,
@@ -11,54 +26,39 @@
 )
 from tensorrt_llm.scaffolding.scaffolding_llm import ScaffoldingLlm
 from tensorrt_llm.scaffolding.task import (
-    AssistantMessage,
     ChatTask,
     MCPCallTask,
     SystemMessage,
     Task,
+    ToolMessage,
     UserMessage,
 )
 from tensorrt_llm.scaffolding.task_collection import (
     DropKVCacheWorkerTag,
     QueryCollector,
     TaskMetricsCollector,
-    drop_kv_cache_scope,
+    TokenizeWorkerTag,
     sub_request_node,
+    tokenize_trace_scope,
+    with_execution_tracing,
     with_task_collection,
 )
 from tensorrt_llm.scaffolding.worker import Worker
 
 from .prompts import (
-    compress_system_prompt,
-    compress_system_prompt_prefix,
-    final_report_generation_prompt,
-    generate_research_brief_prompt,
-    generate_research_brief_prompt_prefix,
-    supervisor_system_prompt,
-    supervisor_system_prompt_prefix,
+    COMPRESSOR_SYSTEM_PROMPT,
+    FINAL_REPORT_GENERATION_PROMPT,
+    GENERATE_RESEARCH_BRIEF_SYSTEM_PROMPT,
+    GENERATE_RESEARCH_BRIEF_USER_PROMPT,
+    SUPERVISOR_SYSTEM_PROMPT,
 )
-from .researcher import Compressor, Researcher, ResearchTask
+from .researcher import Compressor, ResearchChatWithMCPController, Researcher, ResearchTask
 from .tools import complete_research_tool, conduct_research_tool, think_tool
 from .utils import get_today_str
 
 
-@dataclass
-class SupervisorTask(Task):
-    user_prompt: str = field(default=None)
-    research_brief: str = field(default=None)
-    final_report: str = field(default=None)
-
-    @staticmethod
-    def create_from_prompt(prompt: str) -> "SupervisorTask":
-        task = SupervisorTask()
-        task.user_prompt = prompt
-        task.research_brief = None
-        task.final_report = None
-        return task
-
-
-@sub_request_node("AgentDeepResearch", is_top_level=True)
-@drop_kv_cache_scope()
+@sub_request_node("agent_deep_research", is_top_level=True)
+# @drop_kv_cache_scope()
 class Supervisor(Controller):
     tools = [conduct_research_tool, complete_research_tool, think_tool]
     max_research_iter = 12
@@ -91,12 +91,16 @@ def process(self, tasks: List[Task], **kwargs):
         user_topic = [UserMessage(content=supervisor_task.input_str)]
 
         research_brief_messages = [
+            SystemMessage(
+                content=GENERATE_RESEARCH_BRIEF_SYSTEM_PROMPT.format(
+                    date=get_today_str(),
+                ),
+            ),
             UserMessage(
-                content=generate_research_brief_prompt.format(
-                    date=get_today_str(), messages=str(user_topic)
+                content=GENERATE_RESEARCH_BRIEF_USER_PROMPT.format(
+                    messages=str(user_topic),
                 ),
-                prefix=generate_research_brief_prompt_prefix,
-            )
+            ),
         ]
 
         research_brief_task = ChatTask.create_from_messages(messages=research_brief_messages)
@@ -109,19 +113,17 @@ def process(self, tasks: List[Task], **kwargs):
             research_brief,
             [
                 SystemMessage(
-                    content=supervisor_system_prompt.format(
+                    content=SUPERVISOR_SYSTEM_PROMPT.format(
                         date=get_today_str(),
                         max_researcher_iterations=self.max_research_iter,
                         max_concurrent_research_units=self.max_concurrent_research_units,
                     ),
-                    prefix=supervisor_system_prompt_prefix,
                 )
             ],
             tools=self.tools,
         )
 
-        findings = []
-
+        research_findings = {}
         for _ in range(self.max_research_iter):
             yield from self.research_planning_controller.process([research_planning_task])
 
@@ -129,28 +131,45 @@ def process(self, tasks: List[Task], **kwargs):
                 break
 
             research_tasks_list = []
+            should_complete = False
 
+            # Every tool_use in the assistant message MUST get a matching
+            # tool_result in the next message — Bedrock / Anthropic enforce
+            # 1:1 pairing. So process every tool_call here; don't ``break``
+            # out of the loop early on ``complete_research`` (that used to
+            # orphan any tool_calls that came after it in the same message).
             for tool_call in research_planning_task.messages[-1].tool_calls:
                 tool_name = tool_call.function.name
-                arguments = json.loads(tool_call.function.arguments)
-
-                research_planning_task.add_message(
-                    AssistantMessage(
-                        f"I have called the tool {tool_name} with arguments: {tool_call.function.arguments}"
-                    )
-                )
+                try:
+                    arguments = json.loads(tool_call.function.arguments)
+                except json.JSONDecodeError:
+                    arguments = {}
 
                 if tool_name == "think_tool":
                     research_planning_task.add_message(
-                        UserMessage(f"Reflection recorded: {arguments['think']}")
+                        ToolMessage(
+                            f"Reflection recorded: {arguments.get('think', '')}",
+                            tool_call_id=tool_call.id,
+                        )
                     )
                 elif tool_name == "conduct_research":
-                    research_tasks_list.append(
-                        [ResearchTask.from_topic(arguments["research_topic"])]
+                    research_task = ResearchTask.from_topic(
+                        arguments.get("research_topic", ""), tool_call.id
                     )
+                    research_tasks_list.append([research_task])
 
                 elif tool_name == "complete_research":
-                    break
+                    research_planning_task.add_message(
+                        ToolMessage("Research completed.", tool_call_id=tool_call.id)
+                    )
+                    should_complete = True
+                else:
+                    research_planning_task.add_message(
+                        ToolMessage(
+                            f"[supervisor] unsupported tool: {tool_name}",
+                            tool_call_id=tool_call.id,
+                        )
+                    )
 
             if len(research_tasks_list) > 0:
                 researcher_controllers = [
@@ -162,29 +181,33 @@ def process(self, tasks: List[Task], **kwargs):
                 yield ParallelProcess(researcher_controllers, research_tasks_list, kwargs_list)
 
                 for research_tasks in research_tasks_list:
+                    findings = research_tasks[0].research_findings
+                    if findings is None:
+                        # Researcher / Compressor failed (e.g., upstream
+                        # exception left ``chat_task.output_str`` unset).
+                        # Emit a non-None placeholder so the ToolMessage
+                        # isn't silently dropped by messages_to_dict_content
+                        # and the corresponding tool_use stays paired.
+                        findings = "[researcher] no findings produced"
                     research_planning_task.add_message(
-                        UserMessage(research_tasks[0].research_result)
+                        ToolMessage(findings, research_tasks[0].tool_call_id)
                     )
-                    findings.append(research_tasks[0].research_result)
-
-        final_report_generation_task = ChatTask.create_from_messages(
-            [
-                SystemMessage(
-                    final_report_generation_prompt.format(
-                        research_brief=research_brief,
-                        messages=research_planning_task.messages_to_dict_content(),
-                        findings=findings,
-                        date=get_today_str(),
-                    ),
-                ),
-            ],
-        )
+                    topic = research_tasks[0].research_topic
+                    research_findings[topic] = findings
 
-        yield from self.final_report_controller.process([final_report_generation_task])
+            if should_complete:
+                break
 
-        final_report = final_report_generation_task.messages[-1].content
+        # Generate final report based on interactions with the user and the research findings
+        # gathered by the researchers.
+        research_planning_task.add_message(
+            UserMessage(FINAL_REPORT_GENERATION_PROMPT.format(date=get_today_str()))
+        )
+        yield from self.final_report_controller.process([research_planning_task])
+        final_report = research_planning_task.messages[-1].content
 
         tasks[0].output_str = final_report
+        tasks[0].output_tokens = tasks[0].output_tokens or []
         return
 
 
@@ -215,23 +238,32 @@ def process(self, tasks: List[Task], **kwargs):
         return
 
 
-def create_open_deep_research_scaffolding_llm(
-    generation_worker: Worker,
-    mcp_worker: Worker,
+def create_open_deep_research_controller(
     max_tokens: int = 16384,
-    max_parallel_requests: int = 1024,
+    max_webpage_tokens: int = 48000,
+    max_tavily_search_chars: int = 6000,
     enable_statistics: bool = False,
     enable_query_collector: bool = False,
-) -> ScaffoldingLlm:
+    enable_tracing: bool = False,
+) -> Controller:
+    """Create the prototype controller for open deep research scaffolding."""
     sampling_params = {
         "temperature": 0.9,
         "max_tokens": max_tokens,
     }
     gerneration_controller = NativeGenerationController(sampling_params=sampling_params)
+    visit_controller = VisitController(
+        generation_controller=gerneration_controller,
+        max_webpage_tokens=max_webpage_tokens,
+    )
+    tavily_controller = TavilyController(
+        generation_controller=gerneration_controller,
+        compress_threshold_chars=max_tavily_search_chars,
+    )
 
     supervisor_type = Supervisor
     compressor_type = Compressor
-    chat_with_mcp_type = ChatWithMCPController
+    chat_with_mcp_type = ResearchChatWithMCPController
     researcher_type = Researcher
     brief_type = BriefController
     research_planning_type = ResearchPlanningController
@@ -246,6 +278,7 @@ def wrap_with_detailed_profiler(controller_type, controller_name):
                 controller_name=controller_name,
                 task_types=[ChatTask, MCPCallTask],
                 enable_print=True,
+                capture_messages=True,
             )(controller_type)
 
         supervisor_type = wrap_with_detailed_profiler(supervisor_type, "Supervisor")
@@ -264,15 +297,21 @@ def wrap_with_detailed_profiler(controller_type, controller_name):
             QueryCollector,
         )(chat_with_mcp_type)
 
+    if enable_tracing:
+        supervisor_type = with_execution_tracing("Supervisor")(supervisor_type)
+        supervisor_type = tokenize_trace_scope()(supervisor_type)
+
     research_chat_with_tools_controller = chat_with_mcp_type(
-        gerneration_controller, max_iterations=1
+        gerneration_controller,
+        visit_controller,
+        tavily_controller,
+        max_iterations=12,
     )
     research_compress_controller = compressor_type(
         gerneration_controller,
         system_prompts=[
             SystemMessage(
-                compress_system_prompt.format(date=get_today_str()),
-                prefix=compress_system_prompt_prefix,
+                COMPRESSOR_SYSTEM_PROMPT.format(date=get_today_str()),
             )
         ],
     )
@@ -285,18 +324,48 @@ def wrap_with_detailed_profiler(controller_type, controller_name):
     research_planning_controller = research_planning_type(sampling_params=sampling_params)
     final_report_controller = final_report_type(sampling_params=sampling_params)
 
-    supervisor_controller = supervisor_type(
+    return supervisor_type(
         brief_controller, research_planning_controller, research_controller, final_report_controller
     )
 
+
+def create_open_deep_research_scaffolding_llm(
+    generation_worker: Worker,
+    mcp_worker: Worker,
+    max_tokens: int = 16384,
+    max_webpage_tokens: int = 48000,
+    max_tavily_search_chars: int = 6000,
+    max_parallel_requests: int = 1024,
+    enable_statistics: bool = False,
+    enable_query_collector: bool = False,
+    enable_tracing: bool = False,
+) -> ScaffoldingLlm:
+    supervisor_controller = create_open_deep_research_controller(
+        max_tokens=max_tokens,
+        max_webpage_tokens=max_webpage_tokens,
+        max_tavily_search_chars=max_tavily_search_chars,
+        enable_statistics=enable_statistics,
+        enable_query_collector=enable_query_collector,
+        enable_tracing=enable_tracing,
+    )
+
+    workers = {
+        NativeGenerationController.WorkerTag.GENERATION: generation_worker,
+        ChatWithMCPController.WorkerTag.TOOLCALL: mcp_worker,
+        VisitController.WorkerTag.TOOL_CALL: mcp_worker,
+        TavilyController.WorkerTag.TOOL_CALL: mcp_worker,
+        DropKVCacheWorkerTag.DROP_KV_CACHE: generation_worker,
+    }
+    if enable_tracing:
+        workers[TokenizeWorkerTag.TOKENIZE] = generation_worker
+
     scaffolding_llm = ScaffoldingLlm(
         supervisor_controller,
-        {
-            NativeGenerationController.WorkerTag.GENERATION: generation_worker,
-            ChatWithMCPController.WorkerTag.TOOLCALL: mcp_worker,
-            DropKVCacheWorkerTag.DROP_KV_CACHE: generation_worker,
-        },
+        workers,
         max_parallel_requests=max_parallel_requests,
     )
 
+    if enable_tracing:
+        scaffolding_llm.enable_output_task_collection()
+
     return scaffolding_llm
diff --git a/tensorrt_llm/scaffolding/contrib/open_deep_research/tools.py b/tensorrt_llm/scaffolding/contrib/open_deep_research/tools.py
index 44f5e4177e9e..540fb031b877 100644
--- a/tensorrt_llm/scaffolding/contrib/open_deep_research/tools.py
+++ b/tensorrt_llm/scaffolding/contrib/open_deep_research/tools.py
@@ -1,7 +1,5 @@
 from tensorrt_llm.scaffolding.task import OpenAIToolDescription
 
-# TODO: Definition of researcher tools subject to certain specifications.
-# TODO: Add more tools (e.g., MCP tools) beyond search.
 conduct_research_tool = OpenAIToolDescription(
     name="conduct_research",
     description="Conduct research on a given topic",
@@ -18,10 +16,85 @@
     parameters={"think": {"type": "string", "description": "The reflection of the research"}},
 )
 
-web_search_tool = OpenAIToolDescription(
-    name="web_search",
-    description="For conducting web searches to gather information",
-    parameters={"query": {"type": "string"}},
+tavily_search_tool = OpenAIToolDescription(
+    name="tavily_search",
+    description=(
+        "Perform web searches via Tavily and return formatted results. "
+        "Accepts one or more queries in a single call."
+    ),
+    parameters={
+        "query": {
+            "type": "array",
+            "items": {
+                "type": "string",
+                "description": "A search query.",
+            },
+            "minItems": 1,
+            "description": "List of search queries (one or more strings).",
+        }
+    },
+)
+
+# google_scholar_tool = OpenAIToolDescription(
+#     name="google_scholar",
+#     description=(
+#         "Search Google Scholar (and optional web via Custom Search) for academic "
+#         "papers and related sources. Accepts one or more queries in a single call."
+#     ),
+#     parameters={
+#         "query": {
+#             "type": "array",
+#             "items": {
+#                 "type": "string",
+#                 "description": "A search query.",
+#             },
+#             "minItems": 1,
+#             "description": "List of search queries (one or more strings).",
+#         },
+#         "limit": {
+#             "type": "integer",
+#             "description": "Optional cap on results per query (server default if omitted).",
+#         },
+#     },
+# )
+
+fetch_webpage_tool = OpenAIToolDescription(
+    name="fetch_webpage",
+    description=(
+        "Fetch raw text from one or more web pages or PDF URLs via the configured "
+        "reader backend (e.g. Jina / ScraperAPI)."
+    ),
+    parameters={
+        "url": {
+            "type": "array",
+            "items": {"type": "string"},
+            "minItems": 1,
+            "description": "URLs to fetch.",
+        },
+        "parse_type": {
+            "type": "string",
+            "enum": ["html", "pdf"],
+            "description": "Whether the URL is HTML or a PDF.",
+        },
+    },
+)
+
+python_interpreter_tool = OpenAIToolDescription(
+    name="python_interpreter",
+    description=(
+        "Execute Python in the configured sandbox. Use print() for output you need "
+        "to see. For calculations, data checks, or parsing scraped text. The "
+        "environment only has basic packages by default; before importing a "
+        "non-basic package, you may first call this tool to install it, for "
+        "example: import subprocess, sys; subprocess.check_call([sys.executable, "
+        "'-m', 'pip', 'install', '<package>'])."
+    ),
+    parameters={
+        "code": {
+            "type": "string",
+            "description": "Python source to execute.",
+        }
+    },
 )
 
 reflection_tool = OpenAIToolDescription(
diff --git a/tensorrt_llm/scaffolding/contrib/tree_of_thought_research/README.md b/tensorrt_llm/scaffolding/contrib/tree_of_thought_research/README.md
new file mode 100644
index 000000000000..99cee8fdbcb0
--- /dev/null
+++ b/tensorrt_llm/scaffolding/contrib/tree_of_thought_research/README.md
@@ -0,0 +1,28 @@
+# Tree-of-Thought Research
+
+This directory contains a research-oriented Tree-of-Thought controller:
+`TOTResearchController`.
+
+The controller expands several candidate thoughts per depth, executes exactly one
+native tool call for each branch, scores the observed branches with the generation
+model, keeps the top branches, and writes the final answer from the selected
+trajectory.
+
+## Tools
+
+The tool schemas are defined locally in `tot_research_controllers.py`:
+
+- `tavily_search` for web search.
+- `fetch_webpage` for reading known URLs through `VisitController`.
+- `python_interpreter` for computation or parsing.
+- `reflection` for planning-only branches.
+
+## Examples
+
+Run a single prompt:
+
+```bash
+python examples/scaffolding/contrib/tree_of_thought_research/run_tot_research.py \
+  --config examples/scaffolding/contrib/open_deep_research/config.example.yaml \
+  --prompt "Use current sources to compare TensorRT-LLM and vLLM for serving LLMs."
+```
diff --git a/tensorrt_llm/scaffolding/contrib/tree_of_thought_research/__init__.py b/tensorrt_llm/scaffolding/contrib/tree_of_thought_research/__init__.py
new file mode 100644
index 000000000000..c44d4e406356
--- /dev/null
+++ b/tensorrt_llm/scaffolding/contrib/tree_of_thought_research/__init__.py
@@ -0,0 +1,11 @@
+from .tot_research_controllers import (
+    TOTResearchController,
+    create_tot_research_controller,
+    create_tot_research_scaffolding_llm,
+)
+
+__all__ = [
+    "TOTResearchController",
+    "create_tot_research_controller",
+    "create_tot_research_scaffolding_llm",
+]
diff --git a/tensorrt_llm/scaffolding/contrib/tree_of_thought_research/prompts.py b/tensorrt_llm/scaffolding/contrib/tree_of_thought_research/prompts.py
new file mode 100644
index 000000000000..0bb9586296fe
--- /dev/null
+++ b/tensorrt_llm/scaffolding/contrib/tree_of_thought_research/prompts.py
@@ -0,0 +1,74 @@
+# ruff: noqa: E501
+
+from tensorrt_llm.scaffolding import system_prompt
+
+EXPANSION_SYSTEM_PROMPT = system_prompt(
+    """You are a tree-of-thought research agent. Produce one concise branch thought in the message content, then call exactly one native tool from the provided list.
+
+Use trajectory observations as evidence. Do not invent observations that are not present in the input.""",
+    name="tree_of_thought_research.expansion_system_prompt",
+)
+
+EXPANSION_INPUT_PROMPT = """Question:
+{question}
+
+Current selected trajectory:
+{trajectory}
+
+Depth: {depth} of {max_depth}
+
+Create one distinct next branch. Choose exactly one available native tool:
+- tavily_search for web search.
+- fetch_webpage for reading known URLs.
+- python_interpreter for computation or parsing. It has only a basic Python
+  environment by default; before importing a non-basic package, first call
+  python_interpreter with code like:
+  import subprocess, sys; subprocess.check_call([sys.executable, "-m", "pip",
+  "install", "<package>"])
+- reflection for planning when no external action is needed.
+- complete_task only when this trajectory is ready to provide the final answer.
+
+The content should be only the branch thought. The tool call must be in the
+native tool_calls field, not written as JSON or markdown text."""
+
+EVALUATION_SYSTEM_PROMPT = system_prompt(
+    """You score tree-of-thought research branches. Return a numeric score and a short rationale.
+
+Use the candidate observation in the user message when judging source quality and usefulness.""",
+    name="tree_of_thought_research.evaluation_system_prompt",
+)
+
+EVALUATION_INPUT_PROMPT = """Question:
+{question}
+
+Candidate branch:
+Thought: {thought}
+Tool: {tool_name}
+Tool arguments: {tool_args}
+Observation:
+{observation}
+
+Score this branch from 0 to 10 for progress toward a correct, evidence-backed
+answer. Consider relevance, source quality, usefulness of the observation, and
+whether this path reduces uncertainty.
+
+Return exactly:
+Score: <number from 0 to 10>
+Reason: <one or two sentences>"""
+
+FINAL_SYSTEM_PROMPT = system_prompt(
+    """You write final answers from a selected tree-of-thought research trajectory.
+
+Use observations from the user message as evidence and do not invent tool results.""",
+    name="tree_of_thought_research.final_system_prompt",
+)
+
+FINAL_INPUT_PROMPT = """Question:
+{question}
+
+Selected tree-of-thought trajectory:
+{trajectory}
+
+Write the final answer in the same language as the question. Be concise when
+the answer is simple, and include source-backed caveats when the observations
+are incomplete."""
diff --git a/tensorrt_llm/scaffolding/contrib/tree_of_thought_research/tools.py b/tensorrt_llm/scaffolding/contrib/tree_of_thought_research/tools.py
new file mode 100644
index 000000000000..4859ce7361f2
--- /dev/null
+++ b/tensorrt_llm/scaffolding/contrib/tree_of_thought_research/tools.py
@@ -0,0 +1,90 @@
+from tensorrt_llm.scaffolding.task import OpenAIToolDescription
+
+TOT_RESEARCH_TOOLS = [
+    OpenAIToolDescription(
+        name="tavily_search",
+        description=(
+            "Search the web via Tavily and return concise result snippets. "
+            "Use this when the branch needs fresh or source-backed facts."
+        ),
+        parameters={
+            "query": {
+                "type": "array",
+                "items": {"type": "string", "description": "A search query."},
+                "minItems": 1,
+                "description": "One or more web search queries.",
+            }
+        },
+    ),
+    OpenAIToolDescription(
+        name="fetch_webpage",
+        description=(
+            "Fetch and summarize known URLs. Use it after search results identify "
+            "pages that should be read directly."
+        ),
+        parameters={
+            "url": {
+                "type": "array",
+                "items": {"type": "string"},
+                "minItems": 1,
+                "description": "URLs to fetch.",
+            },
+            "goal": {
+                "type": "string",
+                "description": "What information to extract from the page.",
+            },
+            "parse_type": {
+                "type": "string",
+                "enum": ["html", "pdf"],
+                "description": "Whether the URL is an HTML page or a PDF.",
+            },
+        },
+    ),
+    OpenAIToolDescription(
+        name="python_interpreter",
+        description=(
+            "Run Python in the configured sandbox for calculations, parsing, "
+            "or consistency checks. Use print() for required output. The Python "
+            "environment only has basic packages by default; if extra packages "
+            "are needed before import, first call python_interpreter with code "
+            "such as: import subprocess, sys; subprocess.check_call([sys.executable, "
+            "'-m', 'pip', 'install', '<package>'])."
+        ),
+        parameters={
+            "code": {
+                "type": "string",
+                "description": "Python source code to execute.",
+            },
+        },
+    ),
+    OpenAIToolDescription(
+        name="reflection",
+        description=(
+            "Record a planning or reasoning step when no external lookup or "
+            "computation is needed for this branch."
+        ),
+        parameters={
+            "reflection": {
+                "type": "string",
+                "description": "The branch-local reasoning or plan.",
+            }
+        },
+    ),
+    OpenAIToolDescription(
+        name="complete_task",
+        description=(
+            "Use this only when the branch has enough evidence or derivation to "
+            "finish the task. Provide the final answer and concise justification."
+        ),
+        parameters={
+            "answer": {
+                "type": "string",
+                "description": "The final answer for this branch.",
+            },
+            "justification": {
+                "type": "string",
+                "description": "Brief support for why this answer is final.",
+            },
+        },
+    ),
+]
diff --git a/tensorrt_llm/scaffolding/contrib/tree_of_thought_research/tot_research_controllers.py b/tensorrt_llm/scaffolding/contrib/tree_of_thought_research/tot_research_controllers.py
new file mode 100644
index 000000000000..f88abf0d4f88
--- /dev/null
+++ b/tensorrt_llm/scaffolding/contrib/tree_of_thought_research/tot_research_controllers.py
@@ -0,0 +1,544 @@
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+from examples.scaffolding.mcp.fetch_webpage import VisitController, VisitTask
+from examples.scaffolding.mcp.tavily_search import TavilyController, TavilyTask
+from tensorrt_llm.logger import logger
+from tensorrt_llm.scaffolding.controller import (
+    Controller,
+    NativeGenerationController,
+    ParallelProcess,
+)
+from tensorrt_llm.scaffolding.scaffolding_llm import ScaffoldingLlm
+from tensorrt_llm.scaffolding.task import (
+    AssistantMessage,
+    ChatTask,
+    MCPCallTask,
+    OpenAIToolDescription,
+    SystemMessage,
+    Task,
+    UserMessage,
+)
+from tensorrt_llm.scaffolding.task_collection import (
+    DropKVCacheWorkerTag,
+    TaskMetricsCollector,
+    TokenizeWorkerTag,
+    sub_request_node,
+    tokenize_trace_scope,
+    with_execution_tracing,
+    with_task_collection,
+)
+from tensorrt_llm.scaffolding.worker import Worker
+
+from .prompts import (
+    EVALUATION_INPUT_PROMPT,
+    EVALUATION_SYSTEM_PROMPT,
+    EXPANSION_INPUT_PROMPT,
+    EXPANSION_SYSTEM_PROMPT,
+    FINAL_INPUT_PROMPT,
+    FINAL_SYSTEM_PROMPT,
+)
+from .tools import TOT_RESEARCH_TOOLS
+
+
+@dataclass
+class _TOTBranch:
+    thought: str
+    state: str
+    parent: "_TOTBranch | None" = None
+    branch_path: tuple[int, ...] = field(default_factory=tuple)
+    tool_name: str | None = None
+    tool_args: dict[str, Any] = field(default_factory=dict)
+    tool_call_id: str = ""
+    observation: str = ""
+    score: float = 0.0
+    evaluation: str = ""
+    is_complete: bool = False
+    final_answer: str = ""
+
+    def path(self) -> list["_TOTBranch"]:
+        current: _TOTBranch | None = self
+        nodes: list[_TOTBranch] = []
+        while current is not None:
+            nodes.append(current)
+            current = current.parent
+        return list(reversed(nodes))
+
+
+def _parse_tool_arguments(arguments: Any) -> dict[str, Any]:
+    if isinstance(arguments, dict):
+        return arguments
+    if not isinstance(arguments, str) or not arguments.strip():
+        return {}
+    try:
+        parsed = json.loads(arguments)
+    except json.JSONDecodeError:
+        logger.warning("TOTResearch: failed to parse tool arguments: %s", arguments[:200])
+        return {}
+    if not isinstance(parsed, dict):
+        logger.warning("TOTResearch: tool arguments must be a JSON object")
+        return {}
+    return parsed
+
+
+def _json_dumps(value: Any) -> str:
+    return json.dumps(value or {}, ensure_ascii=False)
+
+
+def _truncate_text(text: str, max_length: int) -> str:
+    if len(text) <= max_length:
+        return text
+    return text[:max_length]
+
+
+@sub_request_node("tot_research", is_top_level=True)
+class TOTResearchController(Controller):
+    """Tree-of-thought research controller with native tool calls."""
+
+    class WorkerTag(Enum):
+        TOOL_CALL = "tot_research_tool_call"
+
+    def __init__(
+        self,
+        generation_controller: Controller,
+        visit_controller: VisitController,
+        tavily_controller: TavilyController,
+        tools: list[OpenAIToolDescription] | None = None,
+        max_depth: int = 5,
+        num_thoughts_per_step: int = 3,
+        branch_factor: int = 2,
+        max_observation_length: int = 128000,
+        complete_score_threshold: float = 8.0,
+    ):
+        super().__init__()
+        self.generation_controller = generation_controller
+        self.visit_controller = visit_controller
+        self.tavily_controller = tavily_controller
+        self.tools = tools or TOT_RESEARCH_TOOLS
+        self.max_depth = max_depth
+        self.num_thoughts_per_step = num_thoughts_per_step
+        self.branch_factor = branch_factor
+        self.max_observation_length = max_observation_length
+        self.complete_score_threshold = complete_score_threshold
+
+    def clone(self) -> "TOTResearchController":
+        return TOTResearchController(
+            generation_controller=self.generation_controller.clone(),
+            visit_controller=self.visit_controller.clone(),
+            tavily_controller=self.tavily_controller.clone(),
+            tools=self.tools,
+            max_depth=self.max_depth,
+            num_thoughts_per_step=self.num_thoughts_per_step,
+            branch_factor=self.branch_factor,
+            max_observation_length=self.max_observation_length,
+            complete_score_threshold=self.complete_score_threshold,
+        )
+
+    def process(self, tasks: list[Task], **kwargs):
+        assert len(tasks) == 1, "TOTResearchController only supports one task"
+        question = getattr(tasks[0], "input_str", None) or str(tasks[0])
+        root = _TOTBranch(
+            thought="Start research.",
+            state=f"Question: {question}",
+        )
+        frontier = [root]
+        completed_branches: list[_TOTBranch] = []
+
+        for depth in range(self.max_depth):
+            expansion_tasks = self._make_expansion_tasks(question, frontier, depth)
+            if not expansion_tasks:
+                break
+
+            yield ParallelProcess(
+                [self.generation_controller.clone() for _ in expansion_tasks],
+                [[task] for task, _, _ in expansion_tasks],
+                [{} for _ in expansion_tasks],
+                branch_paths=[branch_path for _, _, branch_path in expansion_tasks],
+            )
+
+            candidates: list[_TOTBranch] = []
+            for chat_task, parent, branch_path in expansion_tasks:
+                candidate = self._branch_from_chat_task(chat_task, parent, branch_path)
+                if candidate is None:
+                    continue
+                yield ParallelProcess.from_generators(
+                    [self._run_tool(candidate, question)],
+                    branch_paths=[candidate.branch_path],
+                )
+                candidate.observation = _truncate_text(
+                    candidate.observation,
+                    self.max_observation_length,
+                )
+                candidate.state = self._render_branch_state(parent.state, candidate)
+                candidates.append(candidate)
+
+            if not candidates:
+                break
+
+            eval_tasks = [
+                ChatTask.create_from_messages(self._evaluation_messages(question, branch))
+                for branch in candidates
+            ]
+            yield ParallelProcess(
+                [self.generation_controller.clone() for _ in eval_tasks],
+                [[task] for task in eval_tasks],
+                [{} for _ in eval_tasks],
+                branch_paths=[branch.branch_path for branch in candidates],
+            )
+            for branch, eval_task in zip(candidates, eval_tasks):
+                branch.evaluation = eval_task.last_assistant_content()
+                branch.score = self._parse_score(branch.evaluation)
+
+            ranked = sorted(candidates, key=lambda item: item.score, reverse=True)
+            completed_branches.extend(branch for branch in ranked if branch.is_complete)
+            completed_frontier = [branch for branch in ranked if branch.is_complete]
+            if completed_frontier and completed_frontier[0].score >= self.complete_score_threshold:
+                frontier = [completed_frontier[0]]
+                break
+
+            frontier = [branch for branch in ranked if not branch.is_complete][
+                : max(1, self.branch_factor)
+            ]
+            if not frontier:
+                frontier = [ranked[0]]
+                break
+
+        final_candidates = frontier + completed_branches
+        best_branch = max(final_candidates, key=lambda item: (item.score, len(item.path())))
+        final_task = ChatTask.create_from_messages(self._final_messages(question, best_branch))
+        yield ParallelProcess.from_generators(
+            [self.generation_controller.process([final_task])],
+            branch_paths=[best_branch.branch_path],
+        )
+
+        tasks[0].output_str = final_task.last_assistant_content()
+        tasks[0].output_tokens = final_task.output_tokens or []
+
+    def _make_expansion_tasks(
+        self,
+        question: str,
+        frontier: list[_TOTBranch],
+        depth: int,
+    ) -> list[tuple[ChatTask, _TOTBranch, tuple[int, ...]]]:
+        expansion_tasks: list[tuple[ChatTask, _TOTBranch, tuple[int, ...]]] = []
+        for branch in frontier:
+            for branch_index in range(max(1, self.num_thoughts_per_step)):
+                task = ChatTask.create_from_messages(
+                    self._expansion_messages(question, branch, depth),
+                    tools=self.tools,
+                )
+                expansion_tasks.append((task, branch, branch.branch_path + (branch_index,)))
+        return expansion_tasks
+
+    def _branch_from_chat_task(
+        self,
+        chat_task: ChatTask,
+        parent: _TOTBranch,
+        branch_path: tuple[int, ...],
+    ) -> _TOTBranch | None:
+        if not chat_task.messages:
+            return None
+        message = chat_task.messages[-1]
+        if not isinstance(message, AssistantMessage):
+            logger.warning("TOTResearch: expected AssistantMessage, got %s", type(message).__name__)
+            return None
+
+        content = (message.content or "").strip()
+        tool_calls = message.tool_calls or []
+        if not tool_calls:
+            logger.warning("TOTResearch: model returned no tool call; using reflection fallback.")
+            if not content:
+                return None
+            return _TOTBranch(
+                thought=content,
+                state="",
+                parent=parent,
+                branch_path=branch_path,
+                tool_name="reflection",
+                tool_args={"reflection": content},
+                tool_call_id=self._branch_tool_call_id(branch_path),
+            )
+
+        tool_call = tool_calls[0]
+        tool_name = tool_call.function.name
+        tool_args = _parse_tool_arguments(tool_call.function.arguments)
+        return _TOTBranch(
+            thought=content or self._thought_from_tool(tool_name, tool_args),
+            state="",
+            parent=parent,
+            branch_path=branch_path,
+            tool_name=tool_name,
+            tool_args=tool_args,
+            tool_call_id=tool_call.id or self._branch_tool_call_id(branch_path),
+        )
+
+    def _run_tool(self, branch: _TOTBranch, question: str):
+        tool_name = branch.tool_name
+        tool_args = branch.tool_args
+        if tool_name == "reflection":
+            branch.observation = str(
+                tool_args.get("reflection") or tool_args.get("think") or branch.thought
+            )
+            return
+
+        if tool_name == "complete_task":
+            branch.is_complete = True
+            branch.final_answer = str(tool_args.get("answer", "")).strip()
+            justification = str(tool_args.get("justification", "")).strip()
+            branch.observation = "\n".join(
+                [
+                    f"Completed with answer: {branch.final_answer}",
+                    f"Justification: {justification}",
+                ]
+            )
+            return
+
+        if tool_name == "fetch_webpage":
+            urls = tool_args.get("url", [])
+            if isinstance(urls, str):
+                urls = [urls]
+            visit_task = VisitTask(
+                urls=urls,
+                goal=tool_args.get("goal", question),
+                parse_type=tool_args.get("parse_type", "html"),
+            )
+            yield from self.visit_controller.process([visit_task])
+            branch.observation = visit_task.result_str or ""
+            return
+
+        if tool_name == "tavily_search":
+            queries = tool_args.get("query", [])
+            if isinstance(queries, str):
+                queries = [queries]
+            tavily_task = TavilyTask(query=queries or [], goal=question)
+            yield from self.tavily_controller.process([tavily_task])
+            branch.observation = tavily_task.result_str or ""
+            if tavily_task.result_stdout:
+                branch.observation += f"\nstdout:\n{tavily_task.result_stdout}"
+            if tavily_task.result_stderr:
+                branch.observation += f"\nstderr:\n{tavily_task.result_stderr}"
+            return
+
+        mcp_task = MCPCallTask.create_mcptask(
+            tool_call_id=branch.tool_call_id or self._branch_tool_call_id(branch.branch_path),
+            tool_name=tool_name or "",
+            args=_json_dumps(tool_args),
+            worker_tag=self.WorkerTag.TOOL_CALL,
+        )
+        yield [mcp_task]
+        branch.observation = mcp_task.result_str or ""
+        if mcp_task.result_stdout:
+            branch.observation += f"\nstdout:\n{mcp_task.result_stdout}"
+        if mcp_task.result_stderr:
+            branch.observation += f"\nstderr:\n{mcp_task.result_stderr}"
+
+    def _expansion_messages(self, question: str, branch: _TOTBranch, depth: int):
+        messages = [
+            SystemMessage(EXPANSION_SYSTEM_PROMPT),
+            UserMessage(
+                EXPANSION_INPUT_PROMPT.format(
+                    question=question,
+                    trajectory=self._render_path(branch),
+                    depth=depth + 1,
+                    max_depth=self.max_depth,
+                )
+            ),
+        ]
+        return messages
+
+    def _evaluation_messages(self, question: str, branch: _TOTBranch):
+        return [
+            SystemMessage(EVALUATION_SYSTEM_PROMPT),
+            UserMessage(
+                EVALUATION_INPUT_PROMPT.format(
+                    question=question,
+                    thought=branch.thought,
+                    tool_name=branch.tool_name,
+                    tool_args=_json_dumps(branch.tool_args),
+                    observation=branch.observation,
+                )
+            ),
+        ]
+
+    def _final_messages(self, question: str, branch: _TOTBranch):
+        messages = [
+            SystemMessage(FINAL_SYSTEM_PROMPT),
+            UserMessage(
+                FINAL_INPUT_PROMPT.format(
+                    question=question,
+                    trajectory=self._render_path(branch),
+                )
+            ),
+        ]
+        return messages
+
+    def _render_path(self, branch: _TOTBranch) -> str:
+        rows: list[str] = []
+        for i, node in enumerate(branch.path()):
+            if i == 0:
+                rows.append(node.state)
+                continue
+            node_rows = [
+                f"Step {i}: {node.thought}",
+                f"Tool: {node.tool_name}({_json_dumps(node.tool_args)})",
+            ]
+            node_rows.append(f"Observation: {node.observation}")
+            node_rows.extend(
+                [
+                    f"Score: {node.score}",
+                    f"Complete: {node.is_complete}",
+                ]
+            )
+            rows.append("\n".join(node_rows))
+        return "\n\n".join(rows)
+
+    def _branch_tool_call_id(self, branch_path: tuple[int, ...]) -> str:
+        path = "_".join(str(item) for item in branch_path) or "root"
+        return f"tot_{path}"
+
+    def _render_branch_state(self, parent_state: str, branch: _TOTBranch) -> str:
+        return "\n\n".join(
+            [
+                parent_state,
+                f"Next thought: {branch.thought}",
+                f"Tool call: {branch.tool_name}({_json_dumps(branch.tool_args)})",
+                f"Observation: {branch.observation}",
+                f"Complete: {branch.is_complete}",
+            ]
+        )
+
+    def _thought_from_tool(self, tool_name: str, tool_args: dict[str, Any]) -> str:
+        if tool_name == "tavily_search":
+            query = tool_args.get("query", "")
+            if isinstance(query, list):
+                query = "; ".join(str(item) for item in query)
+            return f"Search for evidence about: {query}"
+        if tool_name == "fetch_webpage":
+            urls = tool_args.get("url", "")
+            if isinstance(urls, list):
+                urls = ", ".join(str(url) for url in urls)
+            return f"Read source content from: {urls}"
+        if tool_name == "python_interpreter":
+            return "Use Python to compute or verify this branch."
+        if tool_name == "complete_task":
+            return "Complete the task with the final answer."
+        return "Reflect on the current research path."
+
+    def _parse_score(self, text: str) -> float:
+        match = re.search(r"score\s*:\s*(\d+(?:\.\d+)?)", text or "", re.IGNORECASE)
+        if not match:
+            match = re.search(r"(\d+(?:\.\d+)?)", text or "")
+        if not match:
+            return 0.0
+        score = float(match.group(1))
+        return max(0.0, min(10.0, score))
+
+
+def create_tot_research_controller(
+    max_tokens: int = 16384,
+    max_depth: int = 3,
+    num_thoughts_per_step: int = 3,
+    branch_factor: int = 2,
+    max_observation_length: int = 128000,
+    complete_score_threshold: float = 8.0,
+    max_webpage_tokens: int = 48000,
+    max_tavily_search_chars: int = 6000,
+    enable_statistics: bool = False,
+    enable_tracing: bool = False,
+) -> Controller:
+    sampling_params = {
+        # "temperature": 0.7,
+        # "top_p": 0.95,
+        "max_tokens": max_tokens,
+    }
+    generation_controller = NativeGenerationController(sampling_params=sampling_params)
+    visit_controller = VisitController(
+        generation_controller=generation_controller,
+        max_webpage_tokens=max_webpage_tokens,
+    )
+    tavily_controller = TavilyController(
+        generation_controller=generation_controller,
+        compress_threshold_chars=max_tavily_search_chars,
+    )
+
+    controller_type = TOTResearchController
+    if enable_statistics:
+
+        def wrap_with_profiler(controller_cls, name):
+            return with_task_collection(
+                f"{name}TaskCollection",
+                TaskMetricsCollector,
+                controller_name=name,
+                task_types=[ChatTask, MCPCallTask],
+                enable_print=True,
+                capture_messages=True,
+            )(controller_cls)
+
+        controller_type = wrap_with_profiler(controller_type, "TOTResearch")
+
+    if enable_tracing:
+        controller_type = with_execution_tracing("TOTResearch")(controller_type)
+        controller_type = tokenize_trace_scope()(controller_type)
+
+    return controller_type(
+        generation_controller=generation_controller,
+        visit_controller=visit_controller,
+        tavily_controller=tavily_controller,
+        max_depth=max_depth,
+        num_thoughts_per_step=num_thoughts_per_step,
+        branch_factor=branch_factor,
+        max_observation_length=max_observation_length,
+        complete_score_threshold=complete_score_threshold,
+    )
+
+
+def create_tot_research_scaffolding_llm(
+    generation_worker: Worker,
+    mcp_worker: Worker,
+    max_tokens: int = 16384,
+    max_depth: int = 3,
+    num_thoughts_per_step: int = 3,
+    branch_factor: int = 2,
+    max_observation_length: int = 128000,
+    complete_score_threshold: float = 8.0,
+    max_webpage_tokens: int = 48000,
+    max_tavily_search_chars: int = 6000,
+    max_parallel_requests: int = 1024,
+    enable_statistics: bool = False,
+    enable_tracing: bool = False,
+) -> ScaffoldingLlm:
+    controller = create_tot_research_controller(
+        max_tokens=max_tokens,
+        max_depth=max_depth,
+        num_thoughts_per_step=num_thoughts_per_step,
+        branch_factor=branch_factor,
+        max_observation_length=max_observation_length,
+        complete_score_threshold=complete_score_threshold,
+        max_webpage_tokens=max_webpage_tokens,
+        max_tavily_search_chars=max_tavily_search_chars,
+        enable_statistics=enable_statistics,
+        enable_tracing=enable_tracing,
+    )
+    workers = {
+        NativeGenerationController.WorkerTag.GENERATION: generation_worker,
+        TOTResearchController.WorkerTag.TOOL_CALL: mcp_worker,
+        VisitController.WorkerTag.TOOL_CALL: mcp_worker,
+        TavilyController.WorkerTag.TOOL_CALL: mcp_worker,
+        DropKVCacheWorkerTag.DROP_KV_CACHE: generation_worker,
+    }
+    if enable_tracing:
+        workers[TokenizeWorkerTag.TOKENIZE] = generation_worker
+
+    scaffolding_llm = ScaffoldingLlm(
+        controller,
+        workers,
+        max_parallel_requests=max_parallel_requests,
+    )
+    if enable_tracing:
+        scaffolding_llm.enable_output_task_collection()
+    return scaffolding_llm
diff --git a/tensorrt_llm/scaffolding/controller.py b/tensorrt_llm/scaffolding/controller.py
index 1cbe5de92640..788cd1c65a52 100644
--- a/tensorrt_llm/scaffolding/controller.py
+++ b/tensorrt_llm/scaffolding/controller.py
@@ -1,7 +1,7 @@
 import copy
 from abc import ABC
 from enum import Enum
-from typing import Any, List, Mapping, Tuple
+from typing import Any, Generator, List, Mapping, Optional, Sequence, Tuple
 
 import torch
 from torch.nn import functional as F
@@ -11,7 +11,7 @@
 from tensorrt_llm.scaffolding.math_utils import get_digit_majority_vote_result
 from tensorrt_llm.scaffolding.task import (AssistantMessage, ChatTask,
                                            GenerationTask, MCPCallTask, Task,
-                                           UserMessage)
+                                           ToolMessage)
 
 
 class Controller(ABC):
@@ -35,14 +35,45 @@ def process(self, tasks: List[Task], **kwargs):
 
 class ParallelProcess:
 
-    def __init__(self, controllers: List[Controller],
-                 tasks_list: List[List[Task]], kwargs_list: List[Mapping[str,
-                                                                         Any]]):
+    def __init__(self,
+                 controllers: List[Controller],
+                 tasks_list: List[List[Task]],
+                 kwargs_list: List[Mapping[str, Any]],
+                 branch_paths: Optional[Sequence[Sequence[int]]] = None):
         self.sub_gens = []
         for controller, tasks, kwargs in zip(controllers, tasks_list,
                                              kwargs_list):
             gen = controller.process(tasks, **kwargs)
             self.sub_gens.append(gen)
+        self.branch_paths = self._normalize_branch_paths(branch_paths)
+        self._validate_branch_paths()
+
+    # updated for tree_of_thought branching tracing
+    @classmethod
+    def from_generators(
+        cls,
+        sub_gens: Sequence[Generator],
+        branch_paths: Optional[Sequence[Sequence[int]]] = None,
+    ) -> "ParallelProcess":
+        obj = cls.__new__(cls)
+        obj.sub_gens = list(sub_gens)
+        obj.branch_paths = cls._normalize_branch_paths(branch_paths)
+        obj._validate_branch_paths()
+        return obj
+
+    @staticmethod
+    def _normalize_branch_paths(
+        branch_paths: Optional[Sequence[Sequence[int]]],
+    ) -> Optional[List[Tuple[int, ...]]]:
+        if branch_paths is None:
+            return None
+        return [tuple(branch_path) for branch_path in branch_paths]
+
+    def _validate_branch_paths(self):
+        if self.branch_paths is not None and len(self.branch_paths) != len(
+                self.sub_gens):
+            raise ValueError(
+                "branch_paths must match the number of parallel branches")
 
 
 # Controller runs multiple generation tasks.
@@ -244,13 +275,18 @@ def process(self, tasks: List[Task], **kwargs):
         for _ in range(self.max_iterations):
             yield from self.generation_controller.process([chat_task])
             response_message = chat_task.messages[-1]
-            assert isinstance(
-                response_message, AssistantMessage
-            ), f"response is not AssistantMessage, {type(response_message)=}"
-            if response_message.tool_calls is not None:
+            if not isinstance(response_message, AssistantMessage):
+                logger.warning(
+                    "Stopping ChatWithMCP tool loop: expected AssistantMessage "
+                    "after generation, got %s",
+                    type(response_message).__name__,
+                )
+                break
+            if response_message.tool_calls:
                 tool_calls = response_message.tool_calls
                 mcp_tasks = [
-                    MCPCallTask.create_mcptask(tool_call.function.name,
+                    MCPCallTask.create_mcptask(tool_call.id,
+                                               tool_call.function.name,
                                                tool_call.function.arguments,
                                                self.WorkerTag.TOOLCALL)
                     for tool_call in tool_calls
@@ -258,7 +294,17 @@ def process(self, tasks: List[Task], **kwargs):
                 yield mcp_tasks
                 for mcp_task in mcp_tasks:
                     if mcp_task.result_str is not None:
-                        chat_task.add_message(UserMessage(mcp_task.result_str))
+                        chat_task.add_message(
+                            ToolMessage(
+                                mcp_task.result_str,
+                                mcp_task.tool_call_id,
+                                trace_stdout=mcp_task.result_stdout,
+                                trace_stderr=mcp_task.result_stderr,
+                            ))
+                # TODO: this is currently specified for swebench agent
+                if any(tc.function.name == "complete_task"
+                       for tc in tool_calls):
+                    break
             else:
                 break
 
diff --git a/tensorrt_llm/scaffolding/execution_scope.py b/tensorrt_llm/scaffolding/execution_scope.py
new file mode 100644
index 000000000000..ec360d8a564c
--- /dev/null
+++ b/tensorrt_llm/scaffolding/execution_scope.py
@@ -0,0 +1,64 @@
+import contextvars
+from dataclasses import dataclass
+from typing import List, Optional, Sequence, Tuple
+
+
+@dataclass(frozen=True)
+class ExecutionScope:
+    """Identifies a point in the scaffolding execution tree.
+
+    Every scaffolding request gets a root scope (``branch_path == ()``).
+    Each ``ParallelProcess`` fork appends a zero-based branch index,
+    producing a child scope.  The resulting ``scope_id`` is globally
+    unique and can be used as a key for resource ownership (SSE
+    connections, sandboxes, etc.).
+
+    Examples::
+
+        root = ExecutionScope("req-1")  # scope_id = "req-1"
+        child0 = root.child(0)  # scope_id = "req-1:0"
+        child1 = root.child(1)  # scope_id = "req-1:1"
+        grand = child0.child(2)  # scope_id = "req-1:0.2"
+    """
+
+    request_id: str
+    branch_path: Tuple[int, ...] = ()
+
+    @property
+    def scope_id(self) -> str:
+        """Globally unique, hashable key for this scope."""
+        if not self.branch_path:
+            return self.request_id
+        return f"{self.request_id}:{'.'.join(map(str, self.branch_path))}"
+
+    def child(self, branch_index: int) -> "ExecutionScope":
+        """Create a child scope for a parallel fork."""
+        return ExecutionScope(
+            request_id=self.request_id,
+            branch_path=self.branch_path + (branch_index,),
+        )
+
+    def with_branch_path(self, branch_path: Sequence[int]) -> "ExecutionScope":
+        """Create a scope with an explicit branch path for logical trees."""
+        return ExecutionScope(
+            request_id=self.request_id,
+            branch_path=tuple(branch_path),
+        )
+
+    @property
+    def branch_path_list(self) -> List[int]:
+        """Return branch_path as a mutable list (for JSON serialization)."""
+        return list(self.branch_path)
+
+
+current_scope: contextvars.ContextVar[Optional[ExecutionScope]] = contextvars.ContextVar(
+    "current_scope", default=None
+)
+"""The execution scope of the currently running scaffolding code path.
+
+Set automatically by :class:`ScaffoldingLlm` at request entry and at
+each ``ParallelProcess`` fork.  Inherited by every
+``asyncio.create_task`` in the processing chain.  Workers and
+``TaskCollection`` implementations read this to obtain per-request
+or per-branch identity for resource routing, tracing, and replay.
+"""
diff --git a/tensorrt_llm/scaffolding/result.py b/tensorrt_llm/scaffolding/result.py
index 51b67bbf94d6..cbafae3602af 100644
--- a/tensorrt_llm/scaffolding/result.py
+++ b/tensorrt_llm/scaffolding/result.py
@@ -1,5 +1,6 @@
 import asyncio
-from dataclasses import dataclass
+import uuid
+from dataclasses import dataclass, field
 from typing import Any, List, Mapping, Optional, Union
 
 
@@ -7,12 +8,15 @@
 class ScaffoldingOutput:
     text: str
     token_ids: List[int]
+    metadata: Optional[dict] = field(default=None)
 
 
 class ScaffoldingResult:
 
     def __init__(self):
         super().__init__()
+        self._id = str(uuid.uuid4())
+        self.metadata: dict = {}
         self.aqueue = asyncio.Queue()
         #self.cur_output: GenerationResult = None
         self.outputs = []
@@ -21,6 +25,11 @@ def __init__(self):
         self._done = False
         self.task_collections = None
 
+    @property
+    def id(self) -> str:
+        """Unique identifier for this result, auto-generated at creation."""
+        return self._id
+
     def set_output(self, output: Union[ScaffoldingOutput, Any]):
         if isinstance(output, ScaffoldingOutput):
             self.set_output_streaming(output)
diff --git a/tensorrt_llm/scaffolding/scaffolding_llm.py b/tensorrt_llm/scaffolding/scaffolding_llm.py
index 05656d67f863..a8eb1fd0a854 100644
--- a/tensorrt_llm/scaffolding/scaffolding_llm.py
+++ b/tensorrt_llm/scaffolding/scaffolding_llm.py
@@ -1,4 +1,5 @@
 import asyncio
+import logging
 import threading
 import traceback
 from collections import deque
@@ -6,10 +7,13 @@
 from typing import Any, Generator, List, Mapping, Union
 
 from .controller import Controller, ParallelProcess
+from .execution_scope import ExecutionScope, current_scope
 from .result import ScaffoldingResult
 from .task import Task
 from .worker import Worker
 
+logger = logging.getLogger(__name__)
+
 
 @dataclass(frozen=True)
 class ScaffoldingRequest:
@@ -50,7 +54,7 @@ def __init__(
     def __enter__(self):
         return self
 
-    def __exit__(self):
+    def __exit__(self, exc_type, exc_val, exc_tb):
         self.shutdown()
 
     def _get_loop(self):
@@ -90,16 +94,64 @@ async def _handle_task_list(self,
     async def _handle_parallel_process(self,
                                        tasks: ParallelProcess,
                                        request: ScaffoldingRequest = None):
-        """Handle parallel execution of multiple generators."""
+        """Handle parallel execution of multiple generators.
+
+        Creates a child :class:`ExecutionScope` for each branch so that
+        downstream code (workers, tracers, replay) can distinguish
+        concurrent branches.  Resources acquired under a child scope are
+        automatically released when the branch completes.
+        """
+        parent_scope = current_scope.get()
         async_tasks = [
             asyncio.create_task(
-                self._handle_controller_generator(sub_gen, request))
-            for sub_gen in tasks.sub_gens
+                self._handle_branch(
+                    sub_gen,
+                    request,
+                    self._get_parallel_branch_scope(tasks, parent_scope, idx),
+                )) for idx, sub_gen in enumerate(tasks.sub_gens)
         ]
         await asyncio.gather(*async_tasks)
 
+    @staticmethod
+    def _get_parallel_branch_scope(tasks: ParallelProcess,
+                                   parent_scope: ExecutionScope,
+                                   branch_index: int) -> ExecutionScope:
+        if tasks.branch_paths is None:
+            return parent_scope.child(branch_index)
+        return parent_scope.with_branch_path(tasks.branch_paths[branch_index])
+
+    async def _handle_branch(self, gen: Generator, request: ScaffoldingRequest,
+                             scope: ExecutionScope):
+        """Run a single parallel branch under its own scope."""
+        token = current_scope.set(scope)
+        try:
+            await self._handle_controller_generator(gen, request)
+        finally:
+            current_scope.reset(token)
+            await self._notify_scope_end(scope)
+
+    async def _notify_scope_end(self, scope: ExecutionScope):
+        """Inform all workers that *scope* has finished."""
+        for worker in self.workers.values():
+            try:
+                await worker.on_scope_end(scope.scope_id)
+            except Exception:
+                logger.warning(
+                    "Worker %s.on_scope_end(%s) failed",
+                    type(worker).__name__,
+                    scope.scope_id,
+                    exc_info=True,
+                )
+
     async def _handle_single_request(self, request: ScaffoldingRequest):
-        """Process a single scaffolding request."""
+        """Process a single scaffolding request.
+
+        Sets :data:`current_scope` so that every downstream
+        ``asyncio.create_task`` (workers, parallel sub-generators, etc.)
+        inherits the per-request execution scope.
+        """
+        scope = ExecutionScope(request_id=request.result.id)
+        token = current_scope.set(scope)
         try:
             gen = self._create_controller_generator(request)
             await self._handle_controller_generator(gen, request)
@@ -109,6 +161,8 @@ async def _handle_single_request(self, request: ScaffoldingRequest):
             request.result.set_output(None)
             raise
         finally:
+            current_scope.reset(token)
+            await self._notify_scope_end(scope)
             self.running_req_count -= 1
             self._maybe_schedule()
 
@@ -172,6 +226,17 @@ def main_loop_thread():
         self.main_loop_thread.start()
 
     def generate_async(self, prompt: str) -> ScaffoldingResult:
+        """Submit a prompt for asynchronous scaffolding execution.
+
+        Args:
+            prompt: The user prompt to process.
+
+        Returns:
+            A :class:`ScaffoldingResult` whose ``aresult()`` /
+            ``result()`` methods block until execution completes.
+            The result carries a unique :pyattr:`ScaffoldingResult.id`
+            that workers can read via :data:`current_scope`.
+        """
         result = ScaffoldingResult()
 
         async def put_request():
@@ -180,7 +245,8 @@ async def put_request():
                     prompt=prompt,
                     kwargs={},
                     result=result,
-                    controller=self.prototype_controller.clone())
+                    controller=self.prototype_controller.clone(),
+                )
             except Exception as e:
                 self.task_queue.put(None)
                 print(
diff --git a/tensorrt_llm/scaffolding/task.py b/tensorrt_llm/scaffolding/task.py
index 180623212178..82c92032cfcc 100644
--- a/tensorrt_llm/scaffolding/task.py
+++ b/tensorrt_llm/scaffolding/task.py
@@ -1,14 +1,20 @@
+from __future__ import annotations
+
 import json
 from dataclasses import dataclass, field
 from enum import Enum
-from typing import Any, Dict, List, Mapping, Optional, Union
+from typing import TYPE_CHECKING, Any, Dict, List, Mapping, Optional, Union
 
+import openai
 import torch
 
 from tensorrt_llm.executor.result import TokenLogprobs
 
 from .result import ScaffoldingOutput
 
+if TYPE_CHECKING:
+    from .trace_replay.execution_trace import TraceEvent
+
 
 @dataclass
 class Task:
@@ -49,7 +55,7 @@ class GenerationTask(Task):
     input_str: Optional[str] = None
     skip_tokenizer: bool = False
     skip_detokenizer: bool = False
-    #streaming: bool = False
+    # streaming: bool = False
 
     # sampling params for openai
     # Ordered by official OpenAI API documentation
@@ -61,6 +67,7 @@ class GenerationTask(Task):
     logit_bias: Optional[Dict[str, float]] = None
     num_logprobs: Optional[int] = None
     max_tokens: Optional[int] = None
+    min_tokens: Optional[int] = None
     n: int = 1
     presence_penalty: Optional[float] = 0.0
     seed: Optional[int] = None
@@ -83,12 +90,40 @@ class GenerationTask(Task):
     output_str: Optional[str] = None
     output_tokens: Optional[List[int]] = None
     finish_reason: Optional[str] = None
+    llm_request_params: Optional[Dict[str, Any]] = None
     # TODO: support openai API format context logits
     context_logits: Optional[torch.Tensor] = None
     # TODO: don't not use TokenLogprobs for general support
     logprobs: Optional[TokenLogprobs] = None
     customized_result_fields: Dict[str, Any] = field(default_factory=dict)
 
+    # Per-request timing + usage captured by streaming OpenAI workers.
+    # ``ttft_s`` is the wall-time from request submission to the first
+    # server chunk carrying a token (prefill + first decode token + in-flight
+    # scheduler wait); ``latency_s`` is wall-time to the final chunk (full
+    # generation). ``usage_completion_tokens`` / ``usage_prompt_tokens`` come
+    # from the server's ``usage`` chunk (``stream_options.include_usage``)
+    # and are the authoritative per-request token counts — the
+    # ``/v1/completions`` endpoint does not stream ``token_ids`` when
+    # ``detokenize`` is on, so ``len(output_tokens)`` alone is unreliable.
+    # TPOT (tokens-per-output-token) is derived downstream as
+    # ``(latency_s - ttft_s) / (usage_completion_tokens - 1)``, matching
+    # SemiAnalysis's InferenceMAX ``intvty`` definition.
+    ttft_s: Optional[float] = None
+    latency_s: Optional[float] = None
+    usage_completion_tokens: Optional[int] = None
+    usage_prompt_tokens: Optional[int] = None
+
+    # Server-side request id captured from the OpenAI client's streaming
+    # chunks (every chunk's ``chunk.id`` field).  Trace-replay clients use
+    # this to look up the matching record in trtllm-serve's
+    # ``/perf_metrics`` drain and attach per-request KV-cache statistics
+    # (``num_reused_blocks`` / ``num_missed_blocks`` / ``free_num_blocks``)
+    # to the per-LLM-call row in the step JSON.  ``None`` until the worker
+    # observes the first chunk (or when not running against an
+    # OpenAI-compatible server, e.g. the in-process executor path).
+    request_id: Optional[str] = None
+
     @staticmethod
     def create_from_prompt(prompt: str) -> "GenerationTask":
         task = GenerationTask()
@@ -98,7 +133,15 @@ def create_from_prompt(prompt: str) -> "GenerationTask":
         return task
 
     def create_scaffolding_output(self) -> ScaffoldingOutput:
-        return ScaffoldingOutput(self.output_str, self.output_tokens)
+        meta = None
+        # customized for running swebench
+        if self.customized_result_fields:
+            meta = {
+                key: self.customized_result_fields[key]
+                for key in ("swebench_model_patch", "swebench_summary")
+                if key in self.customized_result_fields
+            } or None
+        return ScaffoldingOutput(self.output_str, self.output_tokens, meta)
 
 
 @dataclass
@@ -112,7 +155,7 @@ class StreamGenerationTask(GenerationTask):
     # new tokens that have already been generated.
     streaming_step: Optional[int] = field(default=1)
 
-    #result field
+    # result field
     # worker set this field and identify the same task by this field
     request_handle: Any = field(default=None)
     # worker set this field to True when the generation is finished
@@ -139,7 +182,6 @@ class RewardTask(Task):
 class RoleMessage:
     role: Optional[str] = field(default=None)
     content: Optional[str] = field(default=None)
-    prefix: Optional[str] = field(default=None)
 
     def __str__(self) -> str:
         return json.dumps({
@@ -153,33 +195,39 @@ def __repr__(self) -> str:
     def to_dict(self) -> Dict[str, Any]:
         return {"role": self.role, "content": self.content}
 
-    @classmethod
-    def from_dict(cls, data: Dict[str, Any]):
-        return cls(role=data["role"], content=data["content"])
-
 
 @dataclass
 class UserMessage(RoleMessage):
 
-    def __init__(self, content: str, prefix: Optional[str] = None):
-        super().__init__(role="user", content=content, prefix=prefix)
+    def __init__(self, content: str):
+        super().__init__(role="user", content=content)
 
 
 @dataclass
 class AssistantMessage(RoleMessage):
     reasoning: Optional[str] = field(default=None)
     reasoning_content: Optional[str] = field(default=None)
-    tool_calls: Optional[List[Any]] = field(default=None)
-
-    def __init__(self,
-                 content: str,
-                 reasoning: Optional[str] = None,
-                 reasoning_content: Optional[str] = None,
-                 tool_calls: Optional[List[Any]] = None):
+    tool_calls: Optional[List[
+        openai.types.chat.ChatCompletionMessageFunctionToolCall]] = field(
+            default=None)
+    # Set by the chat worker for the completion that produced this message;
+    # not sent in ``to_dict()`` (OpenAI message schema).
+    finish_reason: Optional[str] = field(default=None)
+
+    def __init__(
+        self,
+        content: str,
+        reasoning: Optional[str] = None,
+        reasoning_content: Optional[str] = None,
+        tool_calls: Optional[List[
+            openai.types.chat.ChatCompletionMessageFunctionToolCall]] = None,
+        finish_reason: Optional[str] = None,
+    ):
         super().__init__(role="assistant", content=content)
         self.reasoning = reasoning
         self.reasoning_content = reasoning_content
         self.tool_calls = tool_calls
+        self.finish_reason = finish_reason
 
     def __str__(self) -> str:
         return json.dumps({
@@ -191,16 +239,76 @@ def __str__(self) -> str:
             self.reasoning,
             "reasoning_content":
             self.reasoning_content,
-            "tool_calls": [str(tool) for tool in self.tool_calls]
+            "tool_calls": [{
+                "id": tool.id,
+                "type": "function",
+                "function": {
+                    "name": tool.function.name,
+                    "arguments": tool.function.arguments,
+                },
+            } for tool in self.tool_calls]
             if self.tool_calls is not None else None,
         })
 
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "role":
+            "assistant",
+            "content":
+            self.content,
+            "tool_calls": [{
+                "id": tool.id,
+                "type": "function",
+                "function": {
+                    "name": tool.function.name,
+                    "arguments": tool.function.arguments,
+                },
+            } for tool in self.tool_calls]
+            if self.tool_calls is not None else None,
+        }
+
 
 @dataclass
 class SystemMessage(RoleMessage):
 
-    def __init__(self, content: str, prefix: Optional[str] = None):
-        super().__init__(role="system", content=content, prefix=prefix)
+    def __init__(self, content: str):
+        super().__init__(role="system", content=content)
+
+
+@dataclass
+class ToolMessage(RoleMessage):
+
+    def __init__(
+        self,
+        content: str,
+        tool_call_id: str,
+        *,
+        trace_stdout: Optional[str] = None,
+        trace_stderr: Optional[str] = None,
+    ):
+        super().__init__(role="tool", content=content)
+        self.tool_call_id = tool_call_id
+        self.trace_stdout = trace_stdout
+        self.trace_stderr = trace_stderr
+
+    def __str__(self) -> str:
+        return json.dumps({
+            "role": "tool",
+            "content": self.content,
+            "tool_call_id": self.tool_call_id,
+        })
+
+    def to_dict(self) -> Dict[str, Any]:
+        d: Dict[str, Any] = {
+            "role": "tool",
+            "content": self.content,
+            "tool_call_id": self.tool_call_id,
+        }
+        if self.trace_stdout is not None:
+            d["trace_stdout"] = self.trace_stdout
+        if self.trace_stderr is not None:
+            d["trace_stderr"] = self.trace_stderr
+        return d
 
 
 class ToolDescription:
@@ -259,10 +367,19 @@ def add_message(self, message: RoleMessage):
     def add_messages(self, messages: list[RoleMessage]):
         self.messages.extend(messages)
 
+    def last_assistant_content(self) -> str:
+        """Return the latest assistant message content, or empty if none."""
+        for message in reversed(self.messages):
+            if isinstance(message, AssistantMessage):
+                return message.content or ""
+        return ""
+
     @staticmethod
-    def create_from_prompt(user_prompt: Optional[str],
-                           system_prompts: Optional[list[SystemMessage]] = None,
-                           tools: Optional[Any] = None) -> "ChatTask":
+    def create_from_prompt(
+        user_prompt: Optional[str],
+        system_prompts: Optional[list[SystemMessage]] = None,
+        tools: Optional[Any] = None,
+    ) -> "ChatTask":
         task = ChatTask()
         if system_prompts is not None:
             task.messages.extend(system_prompts)
@@ -283,16 +400,20 @@ def create_from_messages(messages: list[RoleMessage],
 @dataclass
 class MCPCallTask(Task):
     # mcp inputs
+    tool_call_id: Optional[str] = field(default=None)
     tool_name: Optional[str] = field(default=None)
     args: Optional[dict] = field(default=None)
 
-    #result field
+    # result field
     result_str: Optional[str] = None
+    result_stdout: Optional[str] = None
+    result_stderr: Optional[str] = None
 
     @staticmethod
-    def create_mcptask(tool_name: str, args: dict,
+    def create_mcptask(tool_call_id: str, tool_name: str, args: dict,
                        worker_tag: str) -> "MCPCallTask":
         task = MCPCallTask()
+        task.tool_call_id = tool_call_id
         task.tool_name = tool_name
         task.args = args
         task.worker_tag = worker_tag
@@ -302,23 +423,23 @@ def create_mcptask(tool_name: str, args: dict,
 @dataclass
 class DropKVCacheTask(Task):
     messages_to_retain: list[RoleMessage] = field(default_factory=list)
-    partial_prefix: Optional[str] = field(
-        default=None)  # Currently unused since it's hard to tackle
     chat_task: ChatTask = field(default=None)
 
     def __init__(self, chat_task: ChatTask, worker_tag: str):
         self.worker_tag = worker_tag
 
         self.messages_to_retain = []
-        self.partial_prefix = None
         self.chat_task = chat_task
 
-        retain = True
-        for message in chat_task.messages:
-            if (message.role == "system" or message.role == "user") and retain:
-                if message.prefix is not None:
-                    self.messages_to_retain.append(message)
-                if message.prefix is None or len(message.prefix) < len(
-                        message.content):
-                    self.partial_prefix = message.prefix
-                    retain = False
+        self.messages_to_retain = [
+            message for message in chat_task.messages
+            if message.role in ("system", "user")
+        ]
+
+
+@dataclass
+class TokenizeTask(Task):
+    content: Optional[str] = None
+    event: Optional[TraceEvent] = None
+    token_count: Optional[int] = None
+    tokenize_error: Optional[str] = None
diff --git a/tensorrt_llm/scaffolding/task_collection.py b/tensorrt_llm/scaffolding/task_collection.py
index 762890549035..a6b5ba7f1203 100644
--- a/tensorrt_llm/scaffolding/task_collection.py
+++ b/tensorrt_llm/scaffolding/task_collection.py
@@ -2,10 +2,13 @@
 import os
 import time
 from enum import Enum
-from typing import Any, Dict, List, Tuple, Type
+from typing import Any, Dict, List, Optional, Tuple, Type
 
 from .controller import Controller, ParallelProcess
-from .task import ChatTask, DropKVCacheTask, GenerationTask, MCPCallTask, Task
+from .execution_scope import current_scope
+from .task import (ChatTask, DropKVCacheTask, GenerationTask, MCPCallTask, Task,
+                   TokenizeTask)
+from .trace_replay.execution_trace import ExecutionTrace, TraceEvent
 
 
 class TaskCollection:
@@ -20,6 +23,12 @@ def before_yield(self, tasks: List[Task]):
     def after_yield(self, tasks: List[Task]):
         pass
 
+    def on_parallel_start(self, num_branches: int):
+        pass
+
+    def on_parallel_end(self, num_branches: int):
+        pass
+
     @staticmethod
     def get_global_info() -> Any:
         pass
@@ -49,15 +58,16 @@ def __init__(self, task_collection, gen):
                 def __call__(self):
                     for obj in self.gen:
                         if isinstance(obj, ParallelProcess):
-                            new_sub_gens = []
-                            for sub_gen in obj.sub_gens:
-                                new_sub_gen = TaskCollectionWrapper(
-                                    self.task_collection, sub_gen)
-                                new_sub_gens.append(new_sub_gen)
-                            obj.sub_gens = new_sub_gens
-
+                            num_branches = len(obj.sub_gens)
+                            obj.sub_gens = [
+                                TaskCollectionWrapper(self.task_collection,
+                                                      sub_gen)
+                                for sub_gen in obj.sub_gens
+                            ]
+                            self.task_collection.on_parallel_start(num_branches)
                             yield obj
-                        else:  # obj is a list of tasks
+                            self.task_collection.on_parallel_end(num_branches)
+                        else:
                             self.task_collection.before_yield(obj)
                             yield obj
                             self.task_collection.after_yield(obj)
@@ -200,6 +210,10 @@ class TaskMetricsCollector(TaskCollection):
     Supports filtering by task types and captures additional fields for ChatTask
     including finish_reason, unique_id, and optionally message content.
 
+    For :class:`MCPCallTask`, records ``tool_call_id``, ``tool_name``, ``mcp_args``
+    (arguments as dict when JSON-decodable, else the original value), and
+    ``result_str`` after the worker completes.
+
     When capture_messages is enabled, also captures comprehensive trace information
     including messages, new_messages added during the yield, and sub_request_markers.
     """
@@ -252,6 +266,8 @@ def before_yield(self, tasks: List[Task]):
                 task.enable_token_counting = True
                 if self.capture_messages:
                     self.pre_message_count_map[task_id] = len(task.messages)
+            if self.enable_print:
+                self._print_task_start(task)
 
     def after_yield(self, tasks: List[Task]):
         for task in tasks:
@@ -276,6 +292,9 @@ def after_yield(self, tasks: List[Task]):
                                                      0)
                 task_info['completion_tokens'] = getattr(
                     task, 'completion_tokens_num', 0)
+                task_info['reasoning_tokens'] = getattr(task,
+                                                        'reasoning_tokens_num',
+                                                        0)
                 task_info['total_tokens'] = task_info[
                     'prompt_tokens'] + task_info['completion_tokens']
                 task_info['finish_reason'] = getattr(task, 'finish_reason',
@@ -305,12 +324,34 @@ def after_yield(self, tasks: List[Task]):
                     else:
                         task_info['new_messages'] = []
 
+            elif isinstance(task, MCPCallTask):
+                task_info['tool_call_id'] = task.tool_call_id
+                task_info['tool_name'] = task.tool_name
+                task_info[
+                    'mcp_args'] = TaskMetricsCollector._serialize_mcp_args(
+                        task.args)
+                task_info['result_str'] = task.result_str
+
             TaskMetricsCollector.statistics[self.controller_name].append(
                 task_info)
 
             if self.enable_print:
                 self._print_task_info(task_info)
 
+    @staticmethod
+    def _serialize_mcp_args(args: Any) -> Any:
+        """Normalize MCP task arguments for metrics export."""
+        if args is None:
+            return None
+        if isinstance(args, dict):
+            return args
+        if isinstance(args, str):
+            try:
+                return json.loads(args)
+            except (json.JSONDecodeError, TypeError):
+                return args
+        return args
+
     def _serialize_message(self, message) -> Dict[str, Any]:
         """Serialize a RoleMessage to a dictionary."""
         result = {
@@ -326,8 +367,35 @@ def _serialize_message(self, message) -> Dict[str, Any]:
             result["reasoning_content"] = message.reasoning_content
         if hasattr(message, "tool_calls") and message.tool_calls is not None:
             result["tool_calls"] = [str(tc) for tc in message.tool_calls]
+        if getattr(message, "role", None) == "assistant":
+            fr = getattr(message, "finish_reason", None)
+            if fr is not None:
+                result["finish_reason"] = fr
         return result
 
+    def _print_task_start(self, task: Task):
+        """Print a compact preview before the task is sent to a worker."""
+        log_parts = [
+            f"[{self.controller_name}]",
+            f"{type(task).__name__}",
+            "START",
+        ]
+
+        if isinstance(task, ChatTask):
+            content_chars = sum(
+                len(str(getattr(message, "content", "") or ""))
+                for message in task.messages)
+            tool_count = len(task.tools) if task.tools is not None else 0
+            log_parts.append(
+                f"messages={len(task.messages)} content_chars={content_chars} tools={tool_count}"
+            )
+        elif isinstance(task, MCPCallTask):
+            log_parts.append(
+                f"tool={task.tool_name!r} id={task.tool_call_id!r} "
+                f"args={TaskMetricsCollector._serialize_mcp_args(task.args)!r}")
+
+        print(" | ".join(log_parts))
+
     def _print_task_info(self, task_info: Dict[str, Any]):
         log_parts = [
             f"[{task_info['controller']}]", f"{task_info['task_type']}",
@@ -342,6 +410,15 @@ def _print_task_info(self, task_info: Dict[str, Any]):
 
         print(" | ".join(log_parts))
 
+        if task_info.get('task_type') == 'MCPCallTask':
+            print(f"    MCP tool={task_info.get('tool_name')!r} "
+                  f"id={task_info.get('tool_call_id')!r} "
+                  f"args={task_info.get('mcp_args')!r}")
+            rs = task_info.get('result_str')
+            if rs is not None:
+                preview = rs if len(rs) <= 200 else rs[:200] + "..."
+                print(f"    result_str: {preview}")
+
         # Print message details if capture_messages is enabled
         if 'new_messages' in task_info and task_info['new_messages']:
             print(
@@ -510,6 +587,445 @@ def get_global_info() -> Any:
         return TaskMetricsCollector.statistics
 
 
+class ExecutionTracer(TaskCollection):
+    """Captures the full execution flow of a controller as a chat transcript.
+
+    Every message in a ChatTask conversation becomes its own ``message``
+    event with a ``conversation_id``.  Non-assistant messages (system, user,
+    tool) are emitted in ``before_yield`` as context; assistant messages are
+    emitted in ``after_yield`` with generation metadata (token counts,
+    tool_calls, duration).
+
+    GenerationTask yields produce two ``message`` events: a ``user`` event
+    for the input and an ``assistant`` event for the output.
+
+    MCPCallTask and DropKVCacheTask are recorded as ``tool_call`` and
+    ``drop_kv_cache`` events respectively.  Full traces (see
+    ``ExecutionTrace.save(..., full=True)``) also store MCP arguments,
+    tool results, per-turn LLM latency, request message snapshots, and
+    assistant message bodies.  Each ``message`` event with role ``tool``
+    repeats ``tool_name`` and ``tool_arguments`` from the matching
+    ``tool_call``.  ``llm_request_messages`` preserves the messages sent to
+    the chat completion API; request tool schemas are stored once on the
+    conversation's system message in ``llm_request_tools``.
+
+    Multi-task yields and ParallelProcess forks both produce a
+    ``parallel_start`` / ``parallel_end`` pair with child events recorded
+    as separate top-level events on sub-branch paths.
+
+    Attach via ``@with_execution_tracing`` decorator.
+    After execution, call ``export_trace()`` to obtain an
+    ``ExecutionTrace`` that can be saved to JSON and later replayed.
+    """
+
+    def __init__(self, controller_name: str = "root"):
+        super().__init__()
+        self.controller_name = controller_name
+        self.events: List[TraceEvent] = []
+        self._start_times: Dict[int, float] = {}
+        self._pre_message_counts: Dict[int, int] = {}
+        self._conversation_ids: Dict[int, int] = {}
+        self._last_recorded_counts: Dict[int, int] = {}
+        self._conv_counter = 0
+
+    def _get_conversation_id(self, task_id: int) -> int:
+        """Return a stable conversation_id for a task, assigning one on first encounter."""
+        if task_id not in self._conversation_ids:
+            self._conversation_ids[task_id] = self._conv_counter
+            self._conv_counter += 1
+        return self._conversation_ids[task_id]
+
+    def _is_task_already_traced(self, task: Task) -> bool:
+        return getattr(task, '_tracing_in_progress', False)
+
+    def _mark_task_tracing_start(self, task: Task):
+        task._tracing_in_progress = True
+
+    def _mark_task_tracing_end(self, task: Task):
+        task._tracing_in_progress = False
+
+    def before_yield(self, tasks: List[Task]):
+        for task in tasks:
+            if self._is_task_already_traced(task):
+                continue
+            self._mark_task_tracing_start(task)
+            task_id = id(task)
+            self._start_times[task_id] = time.time()
+
+            if isinstance(task, ChatTask):
+                task.enable_token_counting = True
+                pre_count = len(task.messages)
+                self._pre_message_counts[task_id] = pre_count
+
+                conv_id = self._get_conversation_id(task_id)
+                last_recorded = self._last_recorded_counts.get(task_id, 0)
+                branch_path = self._get_branch_path()
+                llm_request_tools = None
+                if task.tools is not None:
+                    llm_request_tools = [tool.to_dict() for tool in task.tools]
+                for i, msg in enumerate(task.messages[last_recorded:pre_count]):
+                    message_index = last_recorded + i
+                    self.events.append(
+                        self._message_event_from_role_message(
+                            msg,
+                            conv_id,
+                            branch_path,
+                            llm_request_tools=llm_request_tools,
+                            message_index=message_index))
+                self._last_recorded_counts[task_id] = pre_count
+
+    def after_yield(self, tasks: List[Task]):
+        assistant_events: List[TraceEvent] = []
+        now = time.time()
+
+        for task in tasks:
+            task_id = id(task)
+            if task_id not in self._start_times:
+                continue
+
+            duration_ms = (now - self._start_times[task_id]) * 1000
+            del self._start_times[task_id]
+            self._mark_task_tracing_end(task)
+
+            event = self._build_yield_event(task, task_id, duration_ms)
+            if event is not None:
+                assistant_events.append(event)
+
+        if not assistant_events:
+            return
+
+        if len(assistant_events) == 1:
+            self.events.append(assistant_events[0])
+        else:
+            parent_path = self._get_branch_path()
+            self.events.append(
+                TraceEvent(
+                    event_type="parallel_start",
+                    branch_path=parent_path,
+                    num_branches=len(assistant_events),
+                ))
+            for i, ev in enumerate(assistant_events):
+                ev.branch_path = parent_path + [i]
+                self.events.append(ev)
+            self.events.append(
+                TraceEvent(
+                    event_type="parallel_end",
+                    branch_path=parent_path,
+                ))
+
+    def on_parallel_start(self, num_branches: int):
+        self.events.append(
+            TraceEvent(
+                event_type="parallel_start",
+                num_branches=num_branches,
+                branch_path=self._get_branch_path(),
+            ))
+
+    def on_parallel_end(self, num_branches: int):
+        self.events.append(
+            TraceEvent(
+                event_type="parallel_end",
+                branch_path=self._get_branch_path(),
+            ))
+
+    @staticmethod
+    def _get_branch_path() -> List[int]:
+        scope = current_scope.get()
+        return scope.branch_path_list if scope is not None else []
+
+    @staticmethod
+    def _serialize_mcp_args_for_trace(args: Any) -> Any:
+        if args is None:
+            return None
+        if isinstance(args, dict):
+            return args
+        if isinstance(args, str):
+            try:
+                return json.loads(args)
+            except (json.JSONDecodeError, TypeError):
+                return args
+        return args
+
+    @staticmethod
+    def _tool_calls_detail_from_message(msg) -> Optional[List[Dict[str, Any]]]:
+        tc_list = getattr(msg, "tool_calls", None)
+        if not tc_list:
+            return None
+        detail: List[Dict[str, Any]] = []
+        for tc in tc_list:
+            fn = getattr(tc, "function", None)
+            detail.append({
+                "id": getattr(tc, "id", None),
+                "type": getattr(tc, "type", "function"),
+                "function": {
+                    "name": getattr(fn, "name", None),
+                    "arguments": getattr(fn, "arguments", None),
+                } if fn is not None else None,
+            })
+        return detail
+
+    @classmethod
+    def _tool_call_meta_by_id_from_messages(
+            cls, messages) -> Dict[str, Dict[str, Any]]:
+        """Map ``tool_call_id`` to name/arguments from prior assistant ``tool_calls``."""
+        out: Dict[str, Dict[str, Any]] = {}
+        for msg in messages:
+            if getattr(msg, "role", None) != "assistant":
+                continue
+            tcd = cls._tool_calls_detail_from_message(msg)
+            if not tcd:
+                continue
+            for item in tcd:
+                tid = item.get("id")
+                fn = item.get("function") if item else None
+                if not tid or not fn:
+                    continue
+                name = fn.get("name")
+                args = cls._serialize_mcp_args_for_trace(fn.get("arguments"))
+                out[tid] = {"tool_name": name, "tool_arguments": args}
+        return out
+
+    @staticmethod
+    def _serialize_role_message_for_trace(
+        message,
+        tool_meta_by_id: Optional[Dict[str, Dict[str, Any]]] = None,
+    ) -> Dict[str, Any]:
+        """JSON-serializable chat message for full traces (LLM request / context)."""
+        result: Dict[str, Any] = {
+            "role": getattr(message, "role", None),
+            "content": getattr(message, "content", None),
+        }
+        if hasattr(message, "tool_call_id") and getattr(message, "tool_call_id",
+                                                        None):
+            result["tool_call_id"] = message.tool_call_id
+        if getattr(message, "role", None) == "tool":
+            ts = getattr(message, "trace_stdout", None)
+            te = getattr(message, "trace_stderr", None)
+            if ts is not None:
+                result["stdout"] = ts
+            if te is not None:
+                result["stderr"] = te
+            if tool_meta_by_id:
+                tcid = getattr(message, "tool_call_id", None)
+                meta = tool_meta_by_id.get(tcid) if tcid else None
+                if meta is not None:
+                    result["tool_name"] = meta.get("tool_name")
+                    result["tool_arguments"] = meta.get("tool_arguments")
+        if hasattr(message, "reasoning") and message.reasoning is not None:
+            result["reasoning"] = message.reasoning
+        if hasattr(message, "reasoning_content") and getattr(
+                message, "reasoning_content", None) is not None:
+            result["reasoning_content"] = message.reasoning_content
+        tcd = ExecutionTracer._tool_calls_detail_from_message(message)
+        if tcd:
+            result["tool_calls"] = tcd
+        if getattr(message, "role", None) == "assistant":
+            fr = getattr(message, "finish_reason", None)
+            if fr is not None:
+                result["finish_reason"] = fr
+        return result
+
+    def _build_yield_event(self, task: Task, task_id: int,
+                           duration_ms: float) -> Optional[TraceEvent]:
+        """Build the consumable event emitted at a yield point."""
+        branch_path = self._get_branch_path()
+
+        if isinstance(task, ChatTask):
+            pre_count = self._pre_message_counts.pop(task_id, 0)
+            conv_id = self._get_conversation_id(task_id)
+            new_messages = task.messages[pre_count:]
+            self._last_recorded_counts[task_id] = len(task.messages)
+
+            llm_request_messages = [
+                message.to_dict() for message in task.messages[:pre_count]
+                if getattr(message, "content", None) is not None
+            ]
+            first_assistant = None
+            for msg in new_messages:
+                if getattr(msg, "role", None) == "assistant":
+                    first_assistant = msg
+                    break
+            # If a ChatTask yield failed and produced no assistant message,
+            # avoid emitting a synthetic assistant event with zero tokens.
+            if first_assistant is None:
+                return None
+
+            content_val = None
+            reasoning_val = None
+            reasoning_content_val = None
+            tool_calls_detail = None
+            finish_reason_val = getattr(task, 'finish_reason', None)
+            if first_assistant is not None:
+                content_val = getattr(first_assistant, "content", None)
+                reasoning_val = getattr(first_assistant, "reasoning", None)
+                reasoning_content_val = getattr(first_assistant,
+                                                "reasoning_content", None)
+                tool_calls_detail = self._tool_calls_detail_from_message(
+                    first_assistant)
+                msg_fr = getattr(first_assistant, "finish_reason", None)
+                if msg_fr is not None:
+                    finish_reason_val = msg_fr
+
+            return TraceEvent(
+                event_type="message",
+                branch_path=branch_path,
+                conversation_id=conv_id,
+                role="assistant",
+                message_index=pre_count,
+                tool_calls=self._extract_tool_calls(new_messages),
+                prompt_tokens=getattr(task, 'prompt_tokens_num', 0),
+                completion_tokens=getattr(task, 'completion_tokens_num', 0),
+                reasoning_tokens=getattr(task, 'reasoning_tokens_num', 0),
+                finish_reason=finish_reason_val,
+                content=content_val,
+                llm_duration_ms=duration_ms,
+                llm_request_params=getattr(task, "llm_request_params", None),
+                llm_request_messages=llm_request_messages,
+                tool_calls_detail=tool_calls_detail,
+                reasoning=reasoning_val,
+                reasoning_content=reasoning_content_val,
+            )
+        elif isinstance(task, MCPCallTask):
+            return TraceEvent(
+                event_type="tool_call",
+                branch_path=branch_path,
+                duration_ms=duration_ms,
+                tool_call_id=task.tool_call_id,
+                tool_name=task.tool_name,
+                tool_arguments=self._serialize_mcp_args_for_trace(task.args),
+                tool_result=task.result_str,
+                tool_stdout=task.result_stdout,
+                tool_stderr=task.result_stderr,
+            )
+        elif isinstance(task, GenerationTask):
+            conv_id = self._conv_counter
+            self._conv_counter += 1
+
+            user_content = getattr(task, "input_str", None)
+            self.events.append(
+                TraceEvent(
+                    event_type="message",
+                    branch_path=branch_path,
+                    conversation_id=conv_id,
+                    role="user",
+                    content=user_content,
+                ))
+
+            out_str = getattr(task, "output_str", None)
+            llm_req = None
+            if user_content is not None:
+                llm_req = [{"role": "user", "content": user_content}]
+
+            return TraceEvent(
+                event_type="message",
+                branch_path=branch_path,
+                conversation_id=conv_id,
+                role="assistant",
+                content=out_str,
+                prompt_tokens=(len(task.input_tokens)
+                               if task.input_tokens else 0),
+                completion_tokens=(len(task.output_tokens)
+                                   if task.output_tokens else 0),
+                reasoning_tokens=getattr(task, 'reasoning_tokens_num', 0),
+                finish_reason=getattr(task, 'finish_reason', None),
+                llm_duration_ms=duration_ms,
+                llm_request_params=getattr(task, "llm_request_params", None),
+                llm_request_messages=llm_req,
+            )
+        elif isinstance(task, DropKVCacheTask):
+            return TraceEvent(
+                event_type="drop_kv_cache",
+                branch_path=branch_path,
+            )
+        else:
+            return TraceEvent(
+                event_type="message",
+                branch_path=branch_path,
+                role="assistant",
+            )
+
+    def _tool_call_event_for_tool_message(
+            self, branch_path: List[int],
+            tool_call_id: Optional[str]) -> Optional[TraceEvent]:
+        """Most recent ``tool_call`` on ``branch_path`` matching ``tool_call_id``."""
+        for ev in reversed(self.events):
+            if ev.event_type != "tool_call":
+                continue
+            if ev.branch_path != branch_path:
+                continue
+            if tool_call_id is not None:
+                if ev.tool_call_id == tool_call_id:
+                    return ev
+            else:
+                return ev
+        return None
+
+    def _message_event_from_role_message(
+            self,
+            message,
+            conversation_id: int,
+            branch_path: List[int],
+            llm_request_tools: Optional[List[Dict[str, Any]]] = None,
+            message_index: Optional[int] = None) -> TraceEvent:
+        """Convert a RoleMessage into a non-assistant message event."""
+        role = getattr(message, "role", None)
+        content = getattr(message, "content", None)
+        ev = TraceEvent(
+            event_type="message",
+            branch_path=branch_path,
+            conversation_id=conversation_id,
+            role=role,
+            content=content,
+            message_index=message_index,
+        )
+        if role == "assistant":
+            fr = getattr(message, "finish_reason", None)
+            if fr is not None:
+                ev.finish_reason = fr
+        if role == "system":
+            spid = getattr(content, "system_prompt_id", None)
+            if spid is not None:
+                ev.system_prompt_id = spid
+            if message_index == 0 and llm_request_tools:
+                ev.llm_request_tools = llm_request_tools
+        if role == "tool":
+            ts = getattr(message, "trace_stdout", None)
+            te = getattr(message, "trace_stderr", None)
+            if ts is not None:
+                ev.tool_stdout = ts
+            if te is not None:
+                ev.tool_stderr = te
+            tcid = getattr(message, "tool_call_id", None)
+            match = self._tool_call_event_for_tool_message(branch_path, tcid)
+            if match is not None:
+                ev.tool_name = match.tool_name
+                ev.tool_arguments = match.tool_arguments
+        return ev
+
+    @staticmethod
+    def _extract_tool_calls(output_messages) -> Optional[List[str]]:
+        """Extract tool call names from the first assistant message, or None."""
+        for msg in output_messages:
+            if getattr(msg, "role", None) != "assistant":
+                continue
+            tc_list = getattr(msg, "tool_calls", None)
+            if not tc_list:
+                return None
+            return [tc.function.name for tc in tc_list]
+        return None
+
+    def export_trace(self) -> ExecutionTrace:
+        """Build and return the complete ExecutionTrace for this request."""
+        return ExecutionTrace(events=list(self.events), )
+
+
+def with_execution_tracing(controller_name: str):
+    """Convenience decorator that attaches an ExecutionTracer to a controller."""
+    return with_task_collection("execution_tracer",
+                                ExecutionTracer,
+                                controller_name=controller_name)
+
+
 class SubRequestMarker(TaskCollection):
 
     class UniqueIdGenerator:
@@ -646,3 +1162,98 @@ def wrapper():
         return controller_cls_with_chat_collection
 
     return decorator
+
+
+class TokenizeWorkerTag(Enum):
+    TOKENIZE = "tokenize"
+
+
+def _collect_tokenizable_events(events: List[TraceEvent]) -> List[TraceEvent]:
+    """Collect all user/system/tool message events."""
+    return [
+        ev for ev in events
+        if ev.event_type == "message" and ev.role in ("system", "user", "tool")
+    ]
+
+
+def _balance_system_tokens(events: List[TraceEvent]) -> None:
+    """Force each conversation's system tokens to match the first assistant prompt."""
+    conversations: Dict[int, List[TraceEvent]] = {}
+    for event in events:
+        if event.event_type != "message" or event.conversation_id is None:
+            continue
+        conversations.setdefault(event.conversation_id, []).append(event)
+
+    for messages in conversations.values():
+        system_message = None
+        first_assistant_index = None
+        first_assistant_prompt_tokens = None
+        for index, message in enumerate(messages):
+            if message.role == "system" and system_message is None:
+                system_message = message
+                continue
+            if message.role == "assistant" and message.prompt_tokens is not None:
+                first_assistant_index = index
+                first_assistant_prompt_tokens = message.prompt_tokens
+                break
+
+        if system_message is None or first_assistant_index is None or first_assistant_prompt_tokens is None:
+            continue
+
+        prompt_user_tokens = 0
+        can_balance = True
+        for message in messages[:first_assistant_index]:
+            if message.role != "user":
+                continue
+            if message.tokens is None:
+                can_balance = False
+                break
+            prompt_user_tokens += message.tokens
+        if can_balance:
+            system_message.tokens = first_assistant_prompt_tokens - prompt_user_tokens
+
+
+def tokenize_trace_scope():
+
+    def decorator(controller_cls: Type["Controller"]):
+        original_process = controller_cls.process
+
+        def new_process(self, tasks: List[Task], **kwargs):
+
+            def wrapper():
+                yield from original_process(self, tasks, **kwargs)
+
+                tracer = self.task_collections.get("execution_tracer")
+                if tracer is None:
+                    return
+
+                tokenizable_events = _collect_tokenizable_events(tracer.events)
+                if not tokenizable_events:
+                    return
+
+                tokenize_tasks = []
+                for event in tokenizable_events:
+                    tokenize_tasks.append(
+                        TokenizeTask(
+                            content=event.content,
+                            event=event,
+                            worker_tag=TokenizeWorkerTag.TOKENIZE,
+                        ))
+                yield tokenize_tasks
+
+                for task in tokenize_tasks:
+                    if task.token_count is not None and task.event is not None:
+                        task.event.tokens = task.token_count
+                        task.event.tokens_source = "tokenize_endpoint"
+                        task.event.tokenize_error = None
+                    elif task.event is not None and task.tokenize_error:
+                        task.event.tokenize_error = task.tokenize_error
+
+                _balance_system_tokens(tracer.events)
+
+            return wrapper()
+
+        controller_cls.process = new_process
+        return controller_cls
+
+    return decorator
diff --git a/tensorrt_llm/scaffolding/trace_replay/__init__.py b/tensorrt_llm/scaffolding/trace_replay/__init__.py
new file mode 100644
index 000000000000..b6c171f9c612
--- /dev/null
+++ b/tensorrt_llm/scaffolding/trace_replay/__init__.py
@@ -0,0 +1,12 @@
+# Copyright (c) 2025, NVIDIA CORPORATION.  All rights reserved.
+from .execution_trace import ExecutionTrace, TraceEvent
+from .replay import QueueExecutor, QueueManager, ReplayEngine, ReplayGenerationStats
+
+__all__ = [
+    "ExecutionTrace",
+    "TraceEvent",
+    "QueueExecutor",
+    "QueueManager",
+    "ReplayEngine",
+    "ReplayGenerationStats",
+]
diff --git a/tensorrt_llm/scaffolding/trace_replay/execution_trace.py b/tensorrt_llm/scaffolding/trace_replay/execution_trace.py
new file mode 100644
index 000000000000..e3d67409a39d
--- /dev/null
+++ b/tensorrt_llm/scaffolding/trace_replay/execution_trace.py
@@ -0,0 +1,205 @@
+import json
+import uuid
+from dataclasses import asdict, dataclass, field, fields
+from typing import Any, Dict, List, Optional
+
+# Keys omitted from the compact trace (``save(..., full=False)``) so the
+# on-disk format matches historical ``*.trace.json`` files.
+_FULL_TRACE_ONLY_KEYS = frozenset(
+    {
+        "llm_duration_ms",
+        "llm_request_params",
+        "llm_request_messages",
+        "llm_request_tools",
+        "tool_calls_detail",
+        "reasoning",
+        "reasoning_content",
+        "tool_arguments",
+        "tool_result",
+        "tool_stdout",
+        "tool_stderr",
+    }
+)
+
+
+def _strip_none(obj):
+    """Recursively remove keys with None values from dicts."""
+    if isinstance(obj, dict):
+        return {k: _strip_none(v) for k, v in obj.items() if v is not None}
+    if isinstance(obj, list):
+        return [_strip_none(item) for item in obj]
+    return obj
+
+
+def _strip_keys(obj, keys):
+    """Recursively remove specified keys from dicts."""
+    if isinstance(obj, dict):
+        return {k: _strip_keys(v, keys) for k, v in obj.items() if k not in keys}
+    if isinstance(obj, list):
+        return [_strip_keys(item, keys) for item in obj]
+    return obj
+
+
+@dataclass
+class TraceEvent:
+    """A single event in the execution trace.
+
+    event_type semantics:
+      - "message": a single message in a conversation.  ``conversation_id``
+        groups messages belonging to the same ChatTask or GenerationTask.
+        ``role`` is "system", "user", "assistant", or "tool".
+        Assistant messages carry generation metadata (token counts,
+        tool_calls, finish_reason).  For ``event_type == "message"`` with
+        ``role == "assistant"``, ``finish_reason`` is the completion
+        finish reason for that turn when known.
+        Non-assistant messages are informational context recorded between yields.
+      - "tool_call": a single MCP tool invocation (MCPCallTask).
+      - "parallel_start": a parallel branching point.  Child events are
+        recorded as separate top-level events on sub-branch paths
+        (``branch_path`` extended with the branch index).  Paired with
+        a ``parallel_end`` event to close the parallel region.
+      - "drop_kv_cache": a KV-cache eviction marker (DropKVCacheTask).
+
+    Full-trace-only fields (see ``ExecutionTrace.save(..., full=True)``):
+      - ``llm_duration_ms``: wall time for the ChatTask / GenerationTask yield
+        (LLM round-trip) in milliseconds.
+      - ``llm_request_params``: non-message/tool request parameters sent to
+        the model API, such as model, sampling params, stop, and extra_body.
+      - ``llm_request_messages``: messages sent to the model for that
+        completion (chat), or a minimal request description.
+      - ``llm_request_tools``: native tool schemas sent with chat requests,
+        stored once on the conversation's system message.
+      - ``tool_calls_detail``: structured native tool_calls on assistant turns.
+      - ``reasoning`` / ``reasoning_content``: assistant reasoning payloads.
+      - ``tool_arguments`` / ``tool_result``: MCP call input and raw result.
+      - ``tool_stdout`` / ``tool_stderr``: sandbox streams for tool responses
+        (``message`` with role ``tool`` and ``tool_call`` events when present).
+      - ``tool_name`` / ``tool_arguments`` on ``message`` with role ``tool``:
+        duplicate of the preceding matching ``tool_call`` event (full trace).
+    """
+
+    event_type: str = ""
+    branch_path: List[int] = field(default_factory=list)
+
+    # -- message fields (event_type == "message") --
+    conversation_id: Optional[int] = None
+    role: Optional[str] = None
+    message_index: Optional[int] = None
+    tool_calls: Optional[List[str]] = None
+    prompt_tokens: Optional[int] = None
+    completion_tokens: Optional[int] = None
+    reasoning_tokens: Optional[int] = None
+    finish_reason: Optional[str] = None
+
+    # -- full trace: LLM turn (event_type == "message", assistant) --
+    llm_duration_ms: Optional[float] = None
+    llm_request_params: Optional[Dict[str, Any]] = None
+    llm_request_messages: Optional[List[Dict[str, Any]]] = None
+    llm_request_tools: Optional[List[Dict[str, Any]]] = None
+    tool_calls_detail: Optional[List[Dict[str, Any]]] = None
+    reasoning: Optional[str] = None
+    reasoning_content: Optional[str] = None
+
+    # -- tool_call fields (event_type == "tool_call") --
+    tool_call_id: Optional[str] = None
+    tool_name: Optional[str] = None
+    duration_ms: Optional[float] = None
+    tool_arguments: Optional[Any] = None
+    tool_result: Optional[str] = None
+    tool_stdout: Optional[str] = None
+    tool_stderr: Optional[str] = None
+
+    # -- parallel_start fields (event_type == "parallel_start") --
+    num_branches: Optional[int] = None
+
+    # -- message content (for system/user messages, used by tokenize_trace_scope) --
+    content: Optional[str] = None
+
+    # -- system prompt template identity (filled when role == "system" and the
+    # message content was wrapped with `system_prompt()`). Stable UUIDv5
+    # derived from the prompt's registered name; emitted in both compact and
+    # full traces so replay/analytics can identify reused templates.
+    system_prompt_id: Optional[str] = None
+
+    # -- tokenization annotation (filled by tokenize_trace_scope) --
+    # tokens_source is "tokenize_endpoint" for direct counts.
+    tokens: Optional[int] = None
+    tokens_source: Optional[str] = None
+    tokenize_error: Optional[str] = None
+
+
+@dataclass
+class ExecutionTrace:
+    """The complete per-request execution trace, serializable to JSON."""
+
+    trace_id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    events: List[TraceEvent] = field(default_factory=list)
+
+    def save(self, path: str, *, full: bool = False):
+        """Serialize and write the trace to a JSON file.
+
+        With ``full=False`` (default), omit message ``content`` and other
+        verbose fields so the file matches the historical compact trace
+        format (token counts and structure only).
+
+        With ``full=True``, write message bodies, LLM request snapshots,
+        structured tool calls, MCP arguments/results, and per-turn timings.
+        """
+        if full:
+            data = {
+                "trace_id": self.trace_id,
+                "events": [_full_trace_event_dict(ev) for ev in self.events],
+            }
+        else:
+            data = {
+                "trace_id": self.trace_id,
+                "events": [_compact_trace_event_dict(ev) for ev in self.events],
+            }
+        with open(path, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, ensure_ascii=False, default=str)
+
+    @classmethod
+    def load(cls, path: str) -> "ExecutionTrace":
+        """Deserialize an ExecutionTrace from a JSON file."""
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+
+        events = [_parse_event(ev) for ev in data.get("events", [])]
+
+        return cls(
+            trace_id=data.get("trace_id", str(uuid.uuid4())),
+            events=events,
+        )
+
+
+_TRACE_EVENT_FIELDS = {f.name for f in fields(TraceEvent)}
+
+
+def _compact_trace_event_dict(ev: TraceEvent) -> dict:
+    """Dict for compact JSON export (backward-compatible with older traces)."""
+    d = _strip_none(asdict(ev))
+    d.pop("content", None)
+    for k in _FULL_TRACE_ONLY_KEYS:
+        d.pop(k, None)
+    # Tool name/args on role=tool messages are full-trace-only (mirror tool_call).
+    if ev.event_type == "message" and ev.role == "tool":
+        d.pop("tool_name", None)
+    return d
+
+
+def _full_trace_event_dict(ev: TraceEvent) -> dict:
+    """Dict for full JSON export; keep tool stdio keys as JSON null when unset."""
+    d = _strip_none(asdict(ev))
+    if ev.event_type == "tool_call":
+        d["tool_stdout"] = ev.tool_stdout
+        d["tool_stderr"] = ev.tool_stderr
+    elif ev.event_type == "message" and ev.role == "tool":
+        d["tool_stdout"] = ev.tool_stdout
+        d["tool_stderr"] = ev.tool_stderr
+    return d
+
+
+def _parse_event(ev_data: dict) -> TraceEvent:
+    """Deserialize a single TraceEvent from a JSON dict."""
+    d = {k: v for k, v in ev_data.items() if k in _TRACE_EVENT_FIELDS}
+    return TraceEvent(**d)
diff --git a/tensorrt_llm/scaffolding/trace_replay/replay.py b/tensorrt_llm/scaffolding/trace_replay/replay.py
new file mode 100644
index 000000000000..9c4278760692
--- /dev/null
+++ b/tensorrt_llm/scaffolding/trace_replay/replay.py
@@ -0,0 +1,938 @@
+import asyncio
+import hashlib
+import random
+import time
+import uuid
+from collections import defaultdict
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+from ..task import GenerationTask, TaskStatus
+from ..worker import Worker
+from .execution_trace import ExecutionTrace, TraceEvent
+
+# ---------------------------------------------------------------------------
+# Deterministic per-branch RNG
+# ---------------------------------------------------------------------------
+#
+# Trace replay generates synthetic token ids for every user / tool / assistant
+# segment via :func:`_generate_random_token_ids`.  Two callers care about
+# determinism:
+#
+#   * cross-pass radix-tree hits — when the same session is re-played a
+#     second time, the prefix tokens it sends must hash bit-for-bit to the
+#     blocks the first pass committed, otherwise no block past the system
+#     prefix can hit (every per-call random redraw branches the radix tree).
+#   * proactive KV-cache drops — the prefix the engine asks the server to
+#     truncate must equal the longest input prompt that engine actually
+#     sent for the corresponding conv id, otherwise the truncate walk
+#     diverges from the cached chain at the first mismatched block.
+#
+# Both fall out of giving every :class:`QueueExecutor` an isolated
+# :class:`random.Random` instance whose seed is a function of the session
+# (or namespace) and the executor's branch path.  Sibling branches under
+# the same ``parallel_start`` therefore each get an independent stream that
+# does not depend on asyncio's interleaving order, and re-playing the same
+# session two times reproduces every draw exactly.
+#
+# The factory pattern ``Callable[[Tuple[int, ...]], random.Random]`` keeps
+# the seeding policy outside this module: callers (e.g. the trace replay
+# client) decide how a session index, pass namespace, etc. compose into a
+# seed.  The default factory returns a freshly-seeded ``Random`` per
+# branch_path, which preserves the historical "non-deterministic across
+# sessions" behaviour bit-for-bit when callers do not opt in.
+
+RngFactory = Callable[[Tuple[int, ...]], random.Random]
+
+
+def _default_rng_factory(_branch_path: Tuple[int, ...]) -> random.Random:
+    """Return a freshly-seeded ``Random`` per branch — non-deterministic.
+
+    Used when the caller does not provide an explicit factory; matches the
+    pre-determinism behaviour where every replay drew from the module-level
+    ``random`` state.
+    """
+    return random.Random()
+
+
+def make_seeded_rng_factory(*seed_parts: Any) -> RngFactory:
+    r"""Build a :data:`RngFactory` seeded by ``(seed_parts, branch_path)``.
+
+    Per-branch seed is a SHA-256 hash of ``(seed_parts, branch_path)``.
+
+    The seed parts are stringified and joined with ``\x00`` so two callers
+    with different conventions (e.g. ``("replay", trace_idx, sess_idx)``
+    vs. ``("replay", "v2", trace_idx, sess_idx)``) cannot collide unless
+    they explicitly compose to the same byte string.  branch_path is
+    appended last so sibling branches under the same parallel get
+    independent streams.
+
+    SHA-256 is used (rather than ``hash()`` or Python's tuple seed) so the
+    seed is stable across Python versions, processes, and PYTHONHASHSEED
+    settings — important because pass-1 and pass-2 of the same experiment
+    typically run in different processes.
+    """
+
+    def factory(branch_path: Tuple[int, ...]) -> random.Random:
+        key = "\x00".join(repr(p) for p in seed_parts)
+        key += "\x00" + repr(tuple(branch_path))
+        digest = hashlib.sha256(key.encode("utf-8")).digest()
+        seed_int = int.from_bytes(digest[:8], "big")
+        return random.Random(seed_int)
+
+    return factory
+
+
+class ReplayGenerationStats:
+    """Per-assistant-generation token metrics collected during trace replay.
+
+    For each assistant :class:`TraceEvent`, records the trace-file
+    ``completion_tokens`` budget, the lengths actually produced by the
+    worker during replay (full decode sequence and content after stripping
+    leading reasoning tokens), and per-request server-side timings
+    (``ttft_s`` / ``latency_s`` / ``usage_completion_tokens``) that the
+    streaming OpenAI worker attaches to the :class:`GenerationTask`. The
+    timings are what the trace-replay Pareto pipeline feeds to TPOT /
+    ``intvty`` percentiles, matching SemiAnalysis's InferenceMAX
+    ``benchmark_serving.py`` definition of per-request tokens/s/user.
+
+    ``session_index`` / ``trace_index`` identify which concurrent session
+    owns this stats object and, when traces are mixed round-robin, which
+    trace in the mix the session is replaying. They are stamped on every
+    recorded entry so per-LLM-call analyses can break the scatter into
+    per-trace clusters without guessing from durations.
+    """
+
+    __slots__ = ("_entries", "parallel_regions", "session_index", "trace_index")
+
+    def __init__(
+        self,
+        *,
+        session_index: Optional[int] = None,
+        trace_index: Optional[int] = None,
+    ) -> None:
+        self._entries: List[Dict[str, Optional[float]]] = []
+        self.parallel_regions: List[Dict[str, float]] = []
+        self.session_index = session_index
+        self.trace_index = trace_index
+
+    def record_assistant(
+        self,
+        *,
+        trace_completion_tokens: int,
+        replay_output_token_len: int,
+        replay_content_token_len: int,
+        reasoning_tokens: int,
+        ttft_s: Optional[float] = None,
+        latency_s: Optional[float] = None,
+        usage_completion_tokens: Optional[int] = None,
+        usage_prompt_tokens: Optional[int] = None,
+        request_id: Optional[str] = None,
+        branch_path: Optional[Tuple[int, ...]] = None,
+        client_request_start_s: Optional[float] = None,
+        client_request_end_s: Optional[float] = None,
+    ) -> None:
+        self._entries.append(
+            {
+                "trace_completion_tokens": trace_completion_tokens,
+                "replay_output_token_len": replay_output_token_len,
+                "replay_content_token_len": replay_content_token_len,
+                "reasoning_tokens": reasoning_tokens,
+                "ttft_s": ttft_s,
+                "latency_s": latency_s,
+                "usage_completion_tokens": usage_completion_tokens,
+                "usage_prompt_tokens": usage_prompt_tokens,
+                "session_index": self.session_index,
+                "trace_index": self.trace_index,
+                "request_id": request_id,
+                "branch_path": list(branch_path) if branch_path is not None else [],
+                "client_request_start_s": client_request_start_s,
+                "client_request_end_s": client_request_end_s,
+            }
+        )
+
+    def record_parallel_region(self, start_s: float, end_s: float) -> None:
+        self.parallel_regions.append(
+            {"start_s": start_s, "end_s": end_s, "duration_s": end_s - start_s}
+        )
+
+    @property
+    def entries(self) -> List[Dict[str, Optional[float]]]:
+        return list(self._entries)
+
+    def sum_trace_completion_tokens(self) -> int:
+        return sum(e["trace_completion_tokens"] for e in self._entries)
+
+    def sum_replay_output_tokens(self) -> int:
+        return sum(e["replay_output_token_len"] for e in self._entries)
+
+
+class RetentionProbeStats:
+    r"""Deferred retention-probe ledger for end-of-run KV-cache retention.
+
+    Collect prefixes during the run, fire probes post-run to measure
+    long-term KV-cache retention.
+
+    During trace replay each :class:`QueueExecutor` calls
+    :meth:`record_pending` at sentinel time (end-of-branch) with the
+    conv id's last assistant-call input prefix.  No server request is
+    issued at that point — the prefix and metadata are stashed in
+    :attr:`_pending`.
+
+    After **all** sessions complete, the caller iterates
+    :attr:`pending_probes` and fires one ``max_tokens=1, ignore_eos=True``
+    :class:`GenerationTask` per entry through the worker, then calls
+    :meth:`record` with the returned ``request_id``.  This gives every
+    probe an identical measurement context: the full post-workload radix
+    tree, with all sessions' generation requests committed and (for
+    ``with_drop``) all sub-agent drops applied.
+
+    The retention rate computed downstream is:
+
+    .. math::
+
+        \\text{retention\\_rate} =
+        \\frac{\\text{num\\_reused\\_blocks}}{\\lceil \\text{prefix\\_len}
+        / \\text{tokens\\_per\\_block} \\rceil}
+
+    100% = the entire chain is still cached at end-of-run; 0% = fully
+    evicted or proactively freed.
+    """
+
+    __slots__ = ("_records", "_pending")
+
+    def __init__(self) -> None:
+        self._records: List[Dict[str, Any]] = []
+        self._pending: List[Dict[str, Any]] = []
+
+    def record_pending(
+        self,
+        *,
+        branch_path: Tuple[int, ...],
+        conv_id: int,
+        prefix: List[int],
+    ) -> None:
+        """Stash a probe definition to be fired after all sessions complete."""
+        self._pending.append(
+            {
+                "branch_path": tuple(branch_path),
+                "conv_id": conv_id,
+                "prefix": list(prefix),
+            }
+        )
+
+    @property
+    def pending_probes(self) -> List[Dict[str, Any]]:
+        return list(self._pending)
+
+    def record(
+        self,
+        *,
+        branch_path: Tuple[int, ...],
+        conv_id: int,
+        request_id: Optional[str],
+        prefix_len: int,
+    ) -> None:
+        self._records.append(
+            {
+                "branch_path": list(branch_path),
+                "conv_id": conv_id,
+                "request_id": request_id,
+                "prefix_len": prefix_len,
+            }
+        )
+
+    @property
+    def records(self) -> List[Dict[str, Any]]:
+        return list(self._records)
+
+
+class DropPathStats:
+    """Per-drop sentinel-probe ledger for the verification harness (P0.6).
+
+    When a :class:`ReplayEngine` is constructed with a non-``None``
+    ``drop_path_stats`` argument, every ``drop_kv_cache`` event the engine
+    handles emits two extra ``max_tokens=1, ignore_eos=True``
+    :class:`GenerationTask` "probes" — one immediately before the truncate
+    POSTs to the server, one immediately after — for every conv id this
+    branch owns.  Each probe's ``request_id`` (server-assigned, captured
+    by the worker from the OpenAI streaming chunk) is recorded here and
+    later joined with trtllm-serve's ``/perf_metrics`` drain to recover
+    ``num_reused_blocks`` (the per-request KV-cache hit count) and
+    ``free_num_blocks`` (the post-call snapshot of the free-block pool).
+
+    The two derived assertions live downstream in the verification driver:
+
+      * **Sentinel probe** (P0.6.a):
+        ``before.num_reused_blocks - after.num_reused_blocks ≥
+        ⌈(prefix_len - num_tokens_to_keep) / tokens_per_block⌉ − epsilon``.
+        Failure means the truncate did not actually free those blocks.
+      * **free_num_blocks delta** (P0.6.c):
+        ``after.free_num_blocks - before.free_num_blocks ≥ 0`` and within
+        the same lower bound.
+
+    The class is stateful but cheap (one dict per probe).  Probes are
+    issued serially per branch, so :attr:`_records` is built without
+    locking.
+    """
+
+    __slots__ = ("_records", "_next_drop_index")
+
+    def __init__(self) -> None:
+        self._records: List[Dict[str, Any]] = []
+        self._next_drop_index = 0
+
+    def next_drop_index(self) -> int:
+        """Return a fresh monotonic index for the next drop event."""
+        idx = self._next_drop_index
+        self._next_drop_index += 1
+        return idx
+
+    def record(
+        self,
+        *,
+        drop_event_index: int,
+        branch_path: Tuple[int, ...],
+        conv_id: int,
+        phase: str,
+        request_id: Optional[str],
+        prefix_len: int,
+        num_tokens_to_keep: int,
+    ) -> None:
+        """Record one before/after probe.  ``phase`` ∈ {"before", "after"}."""
+        if phase not in ("before", "after"):
+            raise ValueError(f"phase must be 'before' or 'after' (got {phase!r})")
+        self._records.append(
+            {
+                "drop_event_index": drop_event_index,
+                "branch_path": list(branch_path),
+                "conv_id": conv_id,
+                "phase": phase,
+                "request_id": request_id,
+                "prefix_len": prefix_len,
+                "num_tokens_to_keep": num_tokens_to_keep,
+            }
+        )
+
+    @property
+    def records(self) -> List[Dict[str, Any]]:
+        return list(self._records)
+
+
+def _generate_random_token_ids(length: int, rng: random.Random) -> List[int]:
+    """Return *length* random token ids in the range [100, 30000].
+
+    Draws are pulled from *rng* — a per-:class:`QueueExecutor`
+    :class:`random.Random` instance keyed off the executor's branch path
+    (see :data:`RngFactory`) — so re-playing the same session a second
+    time produces an identical token-id stream.
+    """
+    if length <= 0:
+        return []
+    return [rng.randint(100, 30000) for _ in range(length)]
+
+
+class QueueExecutor:
+    """Consumes events from a single queue.
+
+    One ``QueueExecutor`` is created per queue by ``QueueManager``.  It runs
+    as an ``asyncio.Task`` that dequeues events until a sentinel (``None``)
+    is received, at which point it sets ``done_event`` and exits.
+
+    Event processing is a placeholder for future work — dequeued events are
+    currently discarded.
+    """
+
+    def __init__(
+        self,
+        queue: asyncio.Queue,
+        trace_id: str,
+        worker: Worker,
+        system_token_cache: Dict[str, List[int]],
+        rng: random.Random,
+        branch_path: Tuple[int, ...],
+        generation_stats: Optional[ReplayGenerationStats] = None,
+        drop_path_stats: Optional[DropPathStats] = None,
+        retention_probe_stats: Optional[RetentionProbeStats] = None,
+    ):
+        self.queue = queue
+        self.trace_id = trace_id
+        self.worker = worker
+        # Shared across QueueExecutors. Keyed by ``event.system_prompt_id`` for
+        # tagged templates so multiple conversations using the same template
+        # share a token-id prefix (simulating a real prefix-cache hit). Falls
+        # back to ``f"conv:{conv_id}"`` for legacy / untagged system prompts.
+        self._system_token_cache = system_token_cache
+        self._rng = rng
+        self._branch_path = branch_path
+        self._generation_stats = generation_stats
+        self._drop_path_stats = drop_path_stats
+        self._retention_probe_stats = retention_probe_stats
+        self._conversation_token_ids: Dict[int, List[List[int]]] = defaultdict(list)
+        # Per-conv: the input prompt of the most recent assistant call.
+        # Captured BEFORE storing the assistant's output back into segments,
+        # so it is exactly the longest prompt the engine actually sent to
+        # the server for that conv id (= the longest chain the server
+        # committed for that conv id).  Used as the prefix for the
+        # end-of-branch retention probe.
+        self._last_gen_input_tokens: Dict[int, List[int]] = {}
+        # Per-conv: token-count of the system message most recently committed
+        # for this conv. Tracked separately because ``_system_token_cache`` is
+        # keyed by template id (``event.system_prompt_id`` or ``"conv:<id>"``),
+        # so it cannot be looked up directly by conv_id at drop_kv_cache time.
+        self._system_token_len: Dict[int, int] = {}
+        self.done_event = asyncio.Event()
+        self._task = asyncio.create_task(self._run())
+
+    async def _run(self):
+        # Always set done_event so :meth:`QueueManager.wait_all_done` cannot
+        # deadlock if ``_handle_message`` / ``worker.run_task`` raises (otherwise
+        # the sentinel path that sets the event is never reached).
+        #
+        # Every dequeued event — including the ``None`` sentinel — must call
+        # ``task_done`` so that :meth:`asyncio.Queue.join` (used by
+        # :meth:`QueueManager.drain_branch` at parallel_start) accurately
+        # reflects "queue currently drained".
+        try:
+            while True:
+                event = await self.queue.get()
+                try:
+                    if event is None:  # sentinel
+                        # Fire end-of-branch retention probes BEFORE returning,
+                        # so the parent ``wait_all_done`` covers them and the
+                        # client's downstream /perf_metrics drain sees the
+                        # probe records.  For a child branch this is at
+                        # parallel_end (immediately after any drop_kv_cache);
+                        # for the root branch it is at end-of-session.
+                        await self._emit_retention_probes()
+                        return
+                    if event.event_type == "tool_call":
+                        await self._handle_tool_call(event)
+                    elif event.event_type == "message":
+                        await self._handle_message(event)
+                    elif event.event_type == "drop_kv_cache":
+                        await self._handle_drop_kv_cache(event)
+                    # other types: no-op
+                finally:
+                    self.queue.task_done()
+        finally:
+            self.done_event.set()
+
+    async def _handle_tool_call(self, event: TraceEvent):
+        duration = event.duration_ms or 0.0
+        if duration > 0:
+            await asyncio.sleep(duration / 1000)
+
+    async def _emit_retention_probes(self):
+        """Stash one probe definition per root-branch conv id for post-run firing.
+
+        Only the root-branch executor (``branch_path == ()``) emits
+        probe definitions — these cover conv 0 (brief) and conv 1
+        (Supervisor planner), which are the headline measurement.
+        Child-branch executors (Researcher conv ids) skip emission so
+        the post-run probe phase does not balloon to N×10 requests; the
+        Researcher panel of the recipe's plot is confirmation-only and
+        not worth the cache pollution that extra probe writes cause.
+
+        No-op when ``retention_probe_stats`` was not attached to the
+        engine.
+        """
+        if self._retention_probe_stats is None:
+            return
+        if self._branch_path:
+            return
+        if not self._last_gen_input_tokens:
+            return
+        for conv_id, prefix in self._last_gen_input_tokens.items():
+            if not prefix:
+                continue
+            self._retention_probe_stats.record_pending(
+                branch_path=self._branch_path,
+                conv_id=conv_id,
+                prefix=prefix,
+            )
+
+    async def _handle_drop_kv_cache(self, event: TraceEvent):
+        """Free radix-tree blocks for every conv id this executor owns.
+
+        Preserves system-prompt blocks.
+
+        At the moment a ``drop_kv_cache`` event arrives, the executor's
+        :attr:`_conversation_token_ids` holds, for each conv id seen on
+        this branch, the exact concatenated token sequence that was sent
+        as the prompt of that conv's most recent assistant call (plus
+        the appended placeholder for that call's output).  That sequence
+        is the longest path the engine ever pushed into the server's
+        radix tree on this branch — so it is the right prefix to walk
+        when issuing the truncate.
+
+        ``num_tokens_to_keep`` is set to the system-prompt token count
+        for conv ids that have one, and 0 for conv ids without.  This
+        keeps the system-prompt blocks explicitly in the radix tree so
+        future sessions that share the same system prefix enjoy
+        guaranteed cache hits regardless of concurrent-session refcount.
+        Conversation content past the system prompt is freed immediately.
+
+        The chains the server committed from its **actual** output
+        tokens (`asstK_actual` leaves siblinged off our placeholder
+        chain at every assistant call) are not on the path we walk
+        here, so they remain in the tree until LRU evicts them — see
+        the "Matching invariant" section of the experiment plan for
+        why this residual is expected.
+        """
+        if not self._conversation_token_ids:
+            return
+
+        prefixes: List[List[int]] = []
+        keeps: List[int] = []
+        conv_ids: List[int] = []
+        for conv_id, segments in self._conversation_token_ids.items():
+            prefix: List[int] = []
+            for segment in segments:
+                prefix.extend(segment)
+            if not prefix:
+                continue
+            prefixes.append(prefix)
+            system_len = self._system_token_len.get(conv_id, 0)
+            keeps.append(system_len)
+            conv_ids.append(conv_id)
+
+        if not prefixes:
+            return
+
+        # If a drop-path verification ledger is attached, fire one
+        # ``max_tokens=1, ignore_eos=True`` probe per (conv_id, phase) pair
+        # immediately before and after the truncate.  Each probe's
+        # request_id is recorded here; the per-request KV-cache hit
+        # accounting is joined in later via /perf_metrics.  The probes
+        # serialize the truncate against a real before/after measurement
+        # so downstream verification can mechanically prove the truncate
+        # actually freed the blocks the engine claimed it did (P0.6.a).
+        #
+        # A short barrier sleep BEFORE the before-probes lets the
+        # executor's main loop finish committing the most-recent real
+        # generation requests' KV blocks to the radix tree.  The OpenAI
+        # streaming response returns the moment the last token is sent
+        # (sequence-finished), but ``storeContextBlocks`` runs at the
+        # NEXT executor iteration's boundary; without this barrier the
+        # before-probe can race that commit and observe a partial radix
+        # tree, which makes ``after.num_reused_blocks > before.num_reused_blocks``
+        # (the commit catches up between the two probes) and breaks the
+        # delta-positive sanity check.
+        drop_index: Optional[int] = None
+        if self._drop_path_stats is not None:
+            await asyncio.sleep(0.5)
+
+            drop_index = self._drop_path_stats.next_drop_index()
+            for conv_id, prefix, keep in zip(conv_ids, prefixes, keeps):
+                probe = GenerationTask(
+                    input_tokens=prefix,
+                    max_tokens=1,
+                    ignore_eos=True,
+                )
+                status = await self.worker.run_task(probe)
+                if status != TaskStatus.SUCCESS:
+                    raise RuntimeError(f"drop-path before-probe failed: status={status}")
+                self._drop_path_stats.record(
+                    drop_event_index=drop_index,
+                    branch_path=self._branch_path,
+                    conv_id=conv_id,
+                    phase="before",
+                    request_id=probe.request_id,
+                    prefix_len=len(prefix),
+                    num_tokens_to_keep=keep,
+                )
+
+        await self.worker.send_kv_cache_truncate_tokens(prefixes, keeps)
+
+        # Wait long enough for the executor's main loop to drain the
+        # ``kv_cache_control_queue`` and apply the truncate.  The HTTP
+        # POST returned the moment the request was enqueued — the
+        # ``KVCacheManager.truncate_blocks`` call does not run until the
+        # executor's per-iteration ``control_requests`` sweep picks it
+        # up next.  Without this barrier, an after-probe issued
+        # immediately after the POST can race the executor loop and
+        # observe pre-truncate cache state, producing a false-negative
+        # in the verification harness (and stale numbers in any other
+        # caller that wants the truncate to be visible to its next
+        # request).  Only triggered when probes will follow; the
+        # headline measurement bursts are fire-and-forget and do not
+        # need to wait.
+        if self._drop_path_stats is not None:
+            # The truncate POST returns the moment the request was
+            # enqueued; the actual ``KVCacheManager.truncate_blocks``
+            # call runs at the next executor iteration's
+            # ``_sync_and_process_kv_cache_control_queue`` callsite
+            # (see py_executor.py).  Empirically, the kvmon log shows
+            # the post-truncate kv-block count change a few seconds
+            # after the POST returns, so the barrier sleep below has
+            # to be conservative.  Used only when verifying.
+            await asyncio.sleep(3.0)
+
+            assert drop_index is not None
+            for conv_id, prefix, keep in zip(conv_ids, prefixes, keeps):
+                probe = GenerationTask(
+                    input_tokens=prefix,
+                    max_tokens=1,
+                    ignore_eos=True,
+                )
+                status = await self.worker.run_task(probe)
+                if status != TaskStatus.SUCCESS:
+                    raise RuntimeError(f"drop-path after-probe failed: status={status}")
+                self._drop_path_stats.record(
+                    drop_event_index=drop_index,
+                    branch_path=self._branch_path,
+                    conv_id=conv_id,
+                    phase="after",
+                    request_id=probe.request_id,
+                    prefix_len=len(prefix),
+                    num_tokens_to_keep=keep,
+                )
+
+    def _store_segment(self, conv_id: int, message_index, token_ids):
+        """Store a token segment, overwriting if message_index is within bounds."""
+        if message_index is not None and message_index < len(self._conversation_token_ids[conv_id]):
+            self._conversation_token_ids[conv_id][message_index] = token_ids
+        else:
+            self._conversation_token_ids[conv_id].append(token_ids)
+
+    async def _handle_message(self, event: TraceEvent):
+        conv_id = event.conversation_id
+        role = event.role
+        message_index = event.message_index
+
+        if role == "system":
+            token_count = event.tokens or 0
+            # Prefer the template-level identity so that different conversations
+            # rendering the same system-prompt template share a token-id prefix.
+            # Untagged events (legacy traces) fall back to the original
+            # per-conversation key, preserving prior behavior.
+            #
+            # Generated token ids are drawn from this executor's per-branch RNG
+            # (the same RNG used by user/tool/assistant segments), so re-playing
+            # the same (session, branch_path) yields an identical token-id
+            # stream. The cache is shared across executors of a single trace, so
+            # whichever branch first sees a given ``cache_key`` writes the
+            # canonical prefix and every later branch reads it back.
+            cache_key = event.system_prompt_id or f"conv:{conv_id}"
+            cached = self._system_token_cache.get(cache_key)
+            if cached is None:
+                cached = _generate_random_token_ids(token_count, self._rng)
+                self._system_token_cache[cache_key] = cached
+            elif len(cached) < token_count:
+                # Same template, longer rendered system message: grow the
+                # cached prefix in place. Subsequent shorter requests will
+                # still slice a prefix that overlaps with this longer one.
+                cached.extend(_generate_random_token_ids(token_count - len(cached), self._rng))
+            # Always hand out a fresh slice. The cache list may be extended
+            # later by a longer request; prior segments stored in
+            # ``_conversation_token_ids`` must remain stable.
+            token_ids = cached[:token_count]
+            self._system_token_len[conv_id] = token_count
+            self._store_segment(conv_id, message_index, token_ids)
+
+        elif role in ("user", "tool"):
+            token_ids = _generate_random_token_ids(event.tokens or 0, self._rng)
+            self._store_segment(conv_id, message_index, token_ids)
+
+        elif role == "assistant":
+            # Build input from all accumulated segments
+            input_tokens = []
+            for segment in self._conversation_token_ids[conv_id]:
+                input_tokens.extend(segment)
+
+            # Capture the assistant call's input prompt as the seed for
+            # this conv's end-of-branch retention probe.  Stored BEFORE
+            # the gen task runs (so even if the gen call fails we still
+            # have the most recent input to probe with), and overwritten
+            # on every assistant call so the final value is the longest
+            # prompt the engine actually sent for this conv.
+            self._last_gen_input_tokens[conv_id] = list(input_tokens)
+
+            completion_tokens = event.completion_tokens or 0
+            reasoning_tokens = event.reasoning_tokens or 0
+            if completion_tokens <= 0:
+                raise ValueError(
+                    "assistant message needs completion_tokens > 0 "
+                    f"(got {event.completion_tokens!r}); cannot run generation"
+                )
+
+            gen_task = GenerationTask(
+                input_tokens=input_tokens,
+                max_tokens=completion_tokens,
+                ignore_eos=True,
+                # Ask trtllm-serve to ship the actual decoded token ids in
+                # each stream chunk (``CompletionRequest.detokenize=False``).
+                # Required for KV-cache alignment: the server commits its
+                # real decode ids into the radix tree, and we need to store
+                # those same ids into the conversation's segment list so
+                # subsequent turns' prompts walk the same chain instead of
+                # sibling-forking at the prev-prompt block boundary. Without
+                # this, the RNG fallback below kicks in and every turn after
+                # one with non-empty content loses ``ceil(content/32)``
+                # blocks of cache hit relative to the ideal upper bound.
+                skip_detokenizer=True,
+            )
+            client_request_start_s = time.perf_counter()
+            status = await self.worker.run_task(gen_task)
+            client_request_end_s = time.perf_counter()
+            if status != TaskStatus.SUCCESS:
+                raise RuntimeError(f"GenerationTask failed with status {status}")
+
+            # Strip leading reasoning tokens, keep only the content portion.
+            # With ``skip_detokenizer=True`` on the GenerationTask above the
+            # server emits its actual decoded ids in each stream chunk's
+            # ``token_ids`` field, so ``gen_task.output_tokens`` is the
+            # real model output and storing ``output_tokens[reasoning:]``
+            # into the segment list keeps the next turn's prompt aligned
+            # with the server's radix tree.
+            output_len = gen_task.usage_completion_tokens
+            if output_len is None:
+                output_tokens = gen_task.output_tokens
+                if output_tokens is not None:
+                    output_len = len(output_tokens)
+                else:
+                    output_len = int(completion_tokens)
+            output_tokens = gen_task.output_tokens
+            if output_tokens is None:
+                # Defensive fallback: should not trigger when running
+                # against a trtllm-serve that honours ``detokenize=False``
+                # (the GenerationTask above sets it). Kept for backward
+                # compatibility with older servers that always detokenize;
+                # note this path produces an RNG placeholder that does NOT
+                # match the server's real decode ids, so subsequent turns
+                # will sibling-fork at the prev-prompt block boundary and
+                # measured per-call hit rate will fall below the upper
+                # bound by ~``ceil(prev_content/32)`` blocks per turn.
+                output_tokens = _generate_random_token_ids(int(output_len), self._rng)
+            content_tokens = output_tokens[reasoning_tokens:]
+            if self._generation_stats is not None:
+                self._generation_stats.record_assistant(
+                    trace_completion_tokens=int(completion_tokens),
+                    replay_output_token_len=len(output_tokens),
+                    replay_content_token_len=len(content_tokens),
+                    reasoning_tokens=int(reasoning_tokens),
+                    ttft_s=gen_task.ttft_s,
+                    latency_s=gen_task.latency_s,
+                    usage_completion_tokens=gen_task.usage_completion_tokens,
+                    usage_prompt_tokens=gen_task.usage_prompt_tokens,
+                    request_id=gen_task.request_id,
+                    branch_path=self._branch_path,
+                    client_request_start_s=client_request_start_s,
+                    client_request_end_s=client_request_end_s,
+                )
+            self._store_segment(conv_id, message_index, content_tokens)
+
+
+class QueueManager:
+    """Manages a pool of ``(asyncio.Queue, QueueExecutor)`` pairs.
+
+    Tracks which ``trace_id`` each queue belongs to and maintains a mapping
+    from ``branch_path`` (as a tuple) to ``queue_id`` for event routing.
+    """
+
+    def __init__(
+        self,
+        worker: Worker,
+        system_token_cache: Dict[str, List[int]],
+        rng_factory: RngFactory,
+        generation_stats: Optional[ReplayGenerationStats] = None,
+        drop_path_stats: Optional[DropPathStats] = None,
+        retention_probe_stats: Optional[RetentionProbeStats] = None,
+    ):
+        self._worker = worker
+        self._system_token_cache = system_token_cache
+        self._rng_factory = rng_factory
+        self._generation_stats = generation_stats
+        self._drop_path_stats = drop_path_stats
+        self._retention_probe_stats = retention_probe_stats
+        self._queues: Dict[str, asyncio.Queue] = {}
+        self._executors: Dict[str, QueueExecutor] = {}
+        self._trace_ids: Dict[str, str] = {}
+        self._branch_to_queue: Dict[Tuple[int, ...], str] = {}
+
+    def allocate_queue(self, trace_id: str, branch_path: Tuple[int, ...]) -> str:
+        """Create a queue + executor pair for *branch_path* and return its queue id.
+
+        Registers *branch_path* against the resulting queue id.
+
+        ``branch_path`` is taken as input here (rather than registered via
+        a separate :meth:`register_branch` call) so the executor can be
+        seeded with the per-branch RNG before its ``_run`` task starts —
+        otherwise the first event the executor pulls from its queue could
+        race the seeding and produce non-deterministic draws.
+        """
+        queue_id = str(uuid.uuid4())
+        queue: asyncio.Queue = asyncio.Queue()
+        executor = QueueExecutor(
+            queue,
+            trace_id,
+            self._worker,
+            self._system_token_cache,
+            self._rng_factory(branch_path),
+            tuple(branch_path),
+            self._generation_stats,
+            self._drop_path_stats,
+            self._retention_probe_stats,
+        )
+        self._queues[queue_id] = queue
+        self._executors[queue_id] = executor
+        self._trace_ids[queue_id] = trace_id
+        self._branch_to_queue[branch_path] = queue_id
+        return queue_id
+
+    def get_queue(self, branch_path: Tuple[int, ...]) -> asyncio.Queue:
+        """Look up a queue by branch_path."""
+        queue_id = self._branch_to_queue[branch_path]
+        return self._queues[queue_id]
+
+    def close_queue(self, queue_id: str):
+        """Send sentinel ``None`` to the queue to signal completion."""
+        self._queues[queue_id].put_nowait(None)
+
+    async def drain_branch(self, branch_path: Tuple[int, ...]):
+        """Block until the executor for *branch_path* has processed every event currently queued.
+
+        Used as a synchronization barrier at ``parallel_start``: in a real
+        agent run, the controller cannot dispatch child sub-tasks until the
+        parent's pre-fork assistant generation (typically the one that
+        produced the fork tool_call) has fully completed. Without this,
+        replay would push child events into freshly-allocated child queues
+        while the parent's last ``worker.run_task`` was still in flight,
+        inflating server-side concurrency above the true agent topology.
+        """
+        queue_id = self._branch_to_queue[branch_path]
+        await self._queues[queue_id].join()
+
+    async def wait_all_done(self, queue_ids: List[str]):
+        """Await ``done_event`` for each executor in *queue_ids*."""
+        await asyncio.gather(*(self._executors[qid].done_event.wait() for qid in queue_ids))
+        for qid in queue_ids:
+            task = self._executors[qid]._task
+            if not task.done():
+                continue
+            if task.cancelled():
+                continue
+            exc = task.exception()
+            if exc is not None:
+                raise exc
+
+    def unregister_queue(self, queue_id: str):
+        """Clean up all mappings for *queue_id*."""
+        self._queues.pop(queue_id, None)
+        self._executors.pop(queue_id, None)
+        self._trace_ids.pop(queue_id, None)
+        # Remove branch_path → queue_id entries
+        to_remove = [bp for bp, qid in self._branch_to_queue.items() if qid == queue_id]
+        for bp in to_remove:
+            del self._branch_to_queue[bp]
+
+
+class ReplayEngine:
+    """Replays an ``ExecutionTrace`` by routing events to per-branch queues.
+
+    The engine owns a ``QueueManager`` and iterates over trace events,
+    creating child queues for ``parallel_start`` events and routing all
+    other events to the queue registered for their ``branch_path``.
+
+    ``system_token_cache`` memoizes the synthetic token ids generated for
+    each conversation's ``role == "system"`` message. Passing a shared dict
+    lets multiple :class:`ReplayEngine` instances (e.g. one per concurrent
+    replay session of the same trace) all resolve the same ``conv_id`` to
+    the same token-id list, so the server's prefix block reuse can hit on
+    the system prefix across sessions; when left ``None`` the engine falls
+    back to a fresh per-instance dict and the system cache is effectively
+    session-local, matching the original behaviour.
+
+    ``rng_factory`` controls the per-branch RNG used by
+    :func:`_generate_random_token_ids` for every user / tool / assistant
+    placeholder draw.  Passing a seeded factory built via
+    :func:`make_seeded_rng_factory` makes the synthetic token-id stream
+    deterministic for the session, which is what lets a second-pass replay
+    of the same session reproduce the prefix tokens the first pass
+    committed to the radix tree (and lets a proactive KV-cache drop walk
+    the same chain).  When left ``None`` the engine uses a fresh
+    :class:`random.Random` per branch — non-deterministic, matching the
+    historical behaviour.
+    """
+
+    def __init__(
+        self,
+        worker: Worker,
+        generation_stats: Optional[ReplayGenerationStats] = None,
+        system_token_cache: Optional[Dict[str, List[int]]] = None,
+        rng_factory: Optional[RngFactory] = None,
+        drop_path_stats: Optional[DropPathStats] = None,
+        retention_probe_stats: Optional[RetentionProbeStats] = None,
+    ):
+        self._generation_stats = generation_stats
+        self._system_token_cache: Dict[str, List[int]] = (
+            system_token_cache if system_token_cache is not None else {}
+        )
+        self.queue_manager = QueueManager(
+            worker=worker,
+            system_token_cache=self._system_token_cache,
+            rng_factory=rng_factory if rng_factory is not None else _default_rng_factory,
+            generation_stats=generation_stats,
+            drop_path_stats=drop_path_stats,
+            retention_probe_stats=retention_probe_stats,
+        )
+
+    async def launch_trace(self, trace: ExecutionTrace):
+        """Iterate *trace.events* and dispatch each event to its queue.
+
+        Flow:
+        1. Allocate a root queue for ``branch_path=()``.
+        2. Walk ``trace.events`` in order:
+           - ``parallel_start``: create child queues, push onto stack.
+           - ``parallel_end``: close children, await completion, clean up.
+           - All others: route to queue matching ``event.branch_path``.
+        3. Close and await the root queue.
+        """
+        trace_id = trace.trace_id
+
+        # Root queue for branch_path = ()
+        root_queue_id = self.queue_manager.allocate_queue(trace_id, ())
+
+        # Each entry: (child_queue_ids, parallel_start_s)
+        parallel_stack: List[Tuple[List[str], float]] = []
+
+        for event in trace.events:
+            if event.event_type == "parallel_start":
+                parent_path = tuple(event.branch_path or ())
+                # Barrier: wait for the parent branch to finish processing
+                # every event queued before this parallel_start. In a real
+                # agent run, child sub-tasks can only be dispatched after
+                # the parent's fork-producing generation has completed, so
+                # children must not start hitting the server while the
+                # parent's last ``worker.run_task`` is still in flight.
+                await self.queue_manager.drain_branch(parent_path)
+                parallel_start_s = time.perf_counter()
+
+                num_branches = event.num_branches or 0
+                child_queue_ids = []
+                for i in range(num_branches):
+                    child_path = parent_path + (i,)
+                    child_qid = self.queue_manager.allocate_queue(trace_id, child_path)
+                    child_queue_ids.append(child_qid)
+                parallel_stack.append((child_queue_ids, parallel_start_s))
+
+            elif event.event_type == "parallel_end":
+                child_queue_ids, parallel_start_s = parallel_stack.pop()
+                for qid in child_queue_ids:
+                    self.queue_manager.close_queue(qid)
+                await self.queue_manager.wait_all_done(child_queue_ids)
+                parallel_end_s = time.perf_counter()
+                if self._generation_stats is not None:
+                    self._generation_stats.record_parallel_region(parallel_start_s, parallel_end_s)
+                for qid in child_queue_ids:
+                    self.queue_manager.unregister_queue(qid)
+
+            else:
+                branch_path = tuple(event.branch_path or ())
+                queue = self.queue_manager.get_queue(branch_path)
+                await queue.put(event)
+
+        # Close and await root queue
+        self.queue_manager.close_queue(root_queue_id)
+        await self.queue_manager.wait_all_done([root_queue_id])
+        self.queue_manager.unregister_queue(root_queue_id)
diff --git a/tensorrt_llm/scaffolding/utils.py b/tensorrt_llm/scaffolding/utils.py
new file mode 100644
index 000000000000..320203204d11
--- /dev/null
+++ b/tensorrt_llm/scaffolding/utils.py
@@ -0,0 +1,64 @@
+# Copyright (c) 2025, NVIDIA CORPORATION.  All rights reserved.
+"""Scaffolding utilities.
+
+:func:`system_prompt` wraps a system-prompt template with a stable
+``system_prompt_id`` (UUIDv5 derived from a registered name).  The tagged
+value is a ``str`` subclass, so it passes through ``SystemMessage(content=...)``
+unchanged and is invisible to call sites that just consume the text.
+
+The id survives ``.format()`` / ``.format_map()`` so templates with
+runtime-context placeholders (e.g. ``{date}``, configuration values, or even
+user-provided fields) keep the same identity after substitution — the id
+identifies the *template*, not the rendered string.
+
+The :class:`ExecutionTracer` reads ``system_prompt_id`` off the message
+content when building a ``role="system"`` :class:`TraceEvent` and emits it
+into both compact and full traces.
+"""
+
+import uuid
+
+# Fixed namespace so UUIDv5(name) is reproducible across runs and processes.
+_SYSTEM_PROMPT_NAMESPACE = uuid.UUID("4f9c4d4e-1c7e-4d8a-9f8a-3c1c0e1c1f3d")
+
+
+class _TaggedSystemPrompt(str):
+    """A :class:`str` carrying a stable ``system_prompt_id``.
+
+    Behaves like the underlying string for every operation; ``.format()`` and
+    ``.format_map()`` re-wrap their result so substitution preserves identity.
+    Other string ops (slicing, ``+``, ``replace``) return a plain ``str`` and
+    drop the tag — that is intentional: those represent meaningfully different
+    content.
+    """
+
+    __slots__ = ("system_prompt_id",)
+
+    def __new__(cls, content: str, system_prompt_id: str) -> "_TaggedSystemPrompt":
+        instance = super().__new__(cls, content)
+        instance.system_prompt_id = system_prompt_id
+        return instance
+
+    def format(self, *args, **kwargs) -> "_TaggedSystemPrompt":
+        return _TaggedSystemPrompt(str.format(self, *args, **kwargs), self.system_prompt_id)
+
+    def format_map(self, mapping) -> "_TaggedSystemPrompt":
+        return _TaggedSystemPrompt(str.format_map(self, mapping), self.system_prompt_id)
+
+    def __reduce__(self):
+        # Make deepcopy / pickle round-trip the tag (dataclasses.asdict deepcopies
+        # field values, and the default str.__reduce__ would call __new__ with one
+        # positional arg, dropping the id).
+        return (_TaggedSystemPrompt, (str(self), self.system_prompt_id))
+
+
+def system_prompt(content: str, *, name: str) -> _TaggedSystemPrompt:
+    """Tag a system-prompt template with a stable UUIDv5 derived from *name*.
+
+    *name* must be unique across the codebase (recommended convention:
+    ``"<project>.<prompt_const_name>"``, e.g. ``"coder.coder_system_prompt"``).
+    The returned value is a ``str`` subclass usable wherever the original
+    template was used; downstream code only sees the text.
+    """
+    system_prompt_id = str(uuid.uuid5(_SYSTEM_PROMPT_NAMESPACE, name))
+    return _TaggedSystemPrompt(content, system_prompt_id)
diff --git a/tensorrt_llm/scaffolding/worker.py b/tensorrt_llm/scaffolding/worker.py
index 257f16fbc359..ad1432934201 100644
--- a/tensorrt_llm/scaffolding/worker.py
+++ b/tensorrt_llm/scaffolding/worker.py
@@ -2,9 +2,12 @@
 import copy
 import json
 import os
+import time
+import types
 from abc import ABC
 from enum import Enum
-from typing import Callable, List, Optional
+from typing import Any, Callable, Dict, List, Optional
+from urllib.parse import urlencode
 
 import httpx
 import openai
@@ -19,7 +22,8 @@
 
 from .result import ScaffoldingOutput
 from .task import (AssistantMessage, ChatTask, DropKVCacheTask, GenerationTask,
-                   MCPCallTask, StreamGenerationTask, Task, TaskStatus)
+                   MCPCallTask, StreamGenerationTask, Task, TaskStatus,
+                   TokenizeTask)
 
 ExecutorCls = GenerationExecutor
 
@@ -45,6 +49,14 @@ async def run_task(self, task: Task) -> TaskStatus:
 
     task_handlers = {}
 
+    async def on_scope_end(self, scope_id: str) -> None:
+        """Called when an :class:`ExecutionScope` finishes.
+
+        Override in subclasses to release resources (SSE connections,
+        sandboxes, etc.) that were acquired under *scope_id*.  The
+        default implementation is a no-op.
+        """
+
     def shutdown(self):
         pass
 
@@ -54,7 +66,7 @@ async def async_shutdown(self):
     def __enter__(self):
         return self
 
-    def __exit__(self):
+    def __exit__(self, exc_type, exc_val, exc_tb):
         self.shutdown()
 
 
@@ -84,15 +96,117 @@ def __init__(
         async_client: openai.AsyncOpenAI,
         model: str,
         kv_cache_hint_enabled: bool = False,
+        extra_body: Optional[Dict[str, Any]] = None,
     ):
+        # Dynamic patch to support KV cache hint
+        async def send_kv_cache_hint(self, task: DropKVCacheTask, params: dict):
+            base_url = str(self.base_url)
+            if not base_url.endswith("/"):
+                base_url += "/"
+            url = base_url + "kv_cache_hints"
+
+            headers = {}
+            if self.api_key is not None:
+                headers["Authorization"] = f"Bearer {self.api_key}"
+
+            kv_cache_hint_params = {
+                "action":
+                "truncate",
+                "messages":
+                [message.to_dict() for message in task.chat_task.messages],
+                "messages_to_retain":
+                [message.to_dict() for message in task.messages_to_retain],
+            }
+
+            # Spread extra_body contents into the request (like OpenAI client does)
+            extra_body = params.pop("extra_body", {})
+            kv_cache_hint_params.update(params)
+            kv_cache_hint_params.update(
+                extra_body)  # Spread extra_body contents
+
+            async with httpx.AsyncClient() as client:
+                return await client.post(
+                    url,
+                    json=kv_cache_hint_params,
+                    headers=headers,
+                )
+
+        async_client.create_kv_cache_hint = types.MethodType(
+            send_kv_cache_hint, async_client)
+
         self.model = model
         self.async_client = async_client
         self.kv_cache_hint_enabled = kv_cache_hint_enabled
+        self.extra_body = copy.deepcopy(
+            extra_body) if extra_body is not None else {}
+
+    async def send_kv_cache_truncate_tokens(
+        self,
+        prefixes: List[List[int]],
+        num_tokens_to_keep: List[int],
+        request_timeout_s: float = 60.0,
+    ) -> None:
+        """POST a token-level KV cache truncate batch to trtllm-serve.
+
+        Free radix-tree blocks the worker previously caused the server to
+        commit (by sending the full ``prefix`` on a generation request).
+        ``num_tokens_to_keep[i]`` is the prefix length to retain in the
+        radix tree for ``prefixes[i]``; everything past that point on the
+        same chain has its refcount decremented, and blocks whose
+        refcount drops to zero are returned to the free pool.
+
+        Hits ``/_control/kv_cache/truncate_tokens`` (added by
+        :class:`tensorrt_llm.serve.control_plane.KVCacheControlPlane`) —
+        a sibling of ``/_control/kv_cache/truncate`` that bypasses
+        ``apply_chat_template`` so the radix-tree walk hashes the exact
+        token-id bytes the caller previously sent on a ``/v1/completions``
+        request.
+
+        The endpoint is rooted at the server's host (NOT under ``/v1``),
+        so we strip the ``/v1`` suffix that the OpenAI client's
+        ``base_url`` typically carries.
+
+        Raises :class:`RuntimeError` on a non-200 response.
+        """
+        if len(prefixes) != len(num_tokens_to_keep):
+            raise ValueError(
+                f"prefixes ({len(prefixes)}) and num_tokens_to_keep "
+                f"({len(num_tokens_to_keep)}) length mismatch")
+        if not prefixes:
+            return
+
+        base_url = str(self.async_client.base_url)
+        # The OpenAI client's base_url is typically ``http://host:port/v1``
+        # or ``http://host:port/v1/``; the control plane lives at
+        # ``http://host:port/_control/...``, one level up.
+        for v1_suffix in ("/v1/", "/v1"):
+            if base_url.endswith(v1_suffix):
+                base_url = base_url[:-len(v1_suffix)]
+                break
+        url = base_url.rstrip("/") + "/_control/kv_cache/truncate_tokens"
+
+        headers = {"Content-Type": "application/json"}
+        api_key = getattr(self.async_client, "api_key", None)
+        if api_key is not None:
+            headers["Authorization"] = f"Bearer {api_key}"
+
+        payload = {
+            "model": self.model,
+            "prefixes": [list(p) for p in prefixes],
+            "num_tokens_to_keep": list(num_tokens_to_keep),
+        }
+
+        async with httpx.AsyncClient(timeout=request_timeout_s) as http:
+            response = await http.post(url, json=payload, headers=headers)
+            if response.status_code != 200:
+                raise RuntimeError(
+                    f"truncate_tokens failed: HTTP {response.status_code} "
+                    f"body={response.text!r}")
 
     def convert_task_params(self, task: GenerationTask | ChatTask):
         params = {
             "model": self.model,
-            "extra_body": {},
+            "extra_body": copy.deepcopy(self.extra_body),
         }
 
         if hasattr(task, "sub_request_markers") and os.environ.get(
@@ -100,7 +214,14 @@ def convert_task_params(self, task: GenerationTask | ChatTask):
             print(f"task.sub_request_markers is {task.sub_request_markers}")
 
         if not isinstance(task, ChatTask):
-            params["prompt"] = task.input_str
+            # Prefer pre-tokenized prompts when available (e.g. trace replay
+            # via ReplayEngine fills ``input_tokens`` with synthetic token ids
+            # and leaves ``input_str`` unset). The OpenAI completions API
+            # natively accepts ``prompt`` as ``List[int]`` alongside ``str``.
+            if task.input_tokens is not None:
+                params["prompt"] = task.input_tokens
+            else:
+                params["prompt"] = task.input_str
             add_param_if_not_none(params, "echo", [task.echo])
 
         add_param_if_not_none(params, "best_of", [task.best_of])
@@ -109,6 +230,7 @@ def convert_task_params(self, task: GenerationTask | ChatTask):
         add_param_if_not_none(params, "logit_bias", [task.logit_bias])
         add_param_if_not_none(params, "logprobs", [task.num_logprobs])
         add_param_if_not_none(params, "max_tokens", [task.max_tokens])
+        add_param_if_not_none(params, "min_tokens", [task.min_tokens])
         add_param_if_not_none(params, "n", [task.n])
         add_param_if_not_none(params, "presence_penalty",
                               [task.presence_penalty])
@@ -119,6 +241,23 @@ def convert_task_params(self, task: GenerationTask | ChatTask):
         add_param_if_not_none(params, "top_p", [task.top_p])
         add_param_if_not_none(params, "user", [task.user])
 
+        # Forward ignore_eos so trace replay (and any caller that must emit an
+        # exact token budget) can bypass EOS early-stop. trtllm-serve surfaces
+        # ignore_eos via extra_body -> SamplingParams.
+        if task.ignore_eos:
+            params["extra_body"]["ignore_eos"] = True
+
+        # Forward skip_detokenizer so trace replay can retrieve the server's
+        # actual decoded token ids in each stream chunk's ``token_ids`` field
+        # (trtllm-serve gates this behind ``CompletionRequest.detokenize``;
+        # see openai_protocol.py and postprocess_handlers.py). Without this,
+        # the replay's per-turn segment store ends up holding RNG placeholder
+        # ids that sibling-fork off the server's real decode chain in the
+        # radix tree, dropping every subsequent turn's prefix hit at the
+        # prev-prompt block boundary. See replay.py for the consequence.
+        if getattr(task, "skip_detokenizer", False):
+            params["extra_body"]["detokenize"] = False
+
         # Override parameters for deterministic inference
         if is_deterministic_mode():
             params["temperature"] = 0.0  # Deterministic sampling
@@ -135,25 +274,117 @@ def convert_task_params(self, task: GenerationTask | ChatTask):
 
         return params
 
-    def fill_generation_task_with_response(self, task: GenerationTask,
-                                           response: openai.Completion):
-        task.output_str = response.choices[0].text
-        task.output_tokens = response.choices[0].token_ids
-        task.finish_reason = response.choices[0].finish_reason
-        task.logprobs = response.choices[0].logprobs
+    @staticmethod
+    def _request_params_for_trace(params: dict) -> dict:
+        return {
+            key: copy.deepcopy(value)
+            for key, value in params.items()
+            if key not in ("messages", "tools", "prompt")
+        }
+
+    @staticmethod
+    def _get_response_field(obj: Any, field: str) -> Any:
+        if isinstance(obj, dict):
+            return obj.get(field)
+        return getattr(obj, field, None)
+
+    @classmethod
+    def _reasoning_content_from_thinking_blocks(cls,
+                                                message: Any) -> Optional[str]:
+        thinking_blocks = cls._get_response_field(message, "thinking_blocks")
+        if not thinking_blocks:
+            return None
+        thinking = cls._get_response_field(thinking_blocks[0], "thinking")
+        return thinking if isinstance(thinking, str) else None
 
     async def generation_handler(self, task: GenerationTask) -> TaskStatus:
+        """Stream one completion and record per-request timing on *task*.
+
+        Uses ``stream=True`` + ``stream_options={"include_usage": True}`` so we
+        can measure TTFT (wall-time from request start to the first chunk that
+        carries a token) and the full per-request ``latency`` (to the final
+        chunk), and pick up ``usage.completion_tokens`` from the trailing
+        usage-only chunk. These are the same per-request quantities
+        SemiAnalysis's ``benchmark_serving.py`` records for the
+        InferenceMAX ``intvty`` headline, letting the trace-replay Pareto
+        pipeline emit ``1000 / median_TPOT`` per LLM call instead of a
+        per-session proxy. See ``intvty_alignment_handoff.md`` §7 (Phase A).
+
+        The trtllm-serve ``/v1/completions`` backend emits ``token_ids`` in
+        each stream chunk only when the request opts out of detokenization
+        (``CompletionRequest.detokenize=False``). Callers that need the
+        actual decoded token ids (e.g. trace replay, which must align its
+        per-conversation segment store with the server's KV-cache radix
+        tree) should set ``task.skip_detokenizer=True`` — see
+        :meth:`convert_task_params`. Callers that only need the count use
+        ``task.usage_completion_tokens`` (authoritative, from the server's
+        ``usage`` chunk) or the known ``max_tokens`` budget.
+        """
         params = self.convert_task_params(task)
-
-        # Make the API call
+        task.llm_request_params = self._request_params_for_trace(params)
+        params["stream"] = True
+        params["stream_options"] = {"include_usage": True}
+
+        text_parts: List[str] = []
+        token_ids_acc: List[int] = []
+        logprobs_acc: List = []
+        finish_reason: Optional[str] = None
+        usage_completion_tokens: Optional[int] = None
+        usage_prompt_tokens: Optional[int] = None
+        ttft_s: Optional[float] = None
+        request_id: Optional[str] = None
+
+        t_start = time.perf_counter()
         try:
-            response = await self.async_client.completions.create(**params)
-            self.fill_generation_task_with_response(task, response)
+            stream = await self.async_client.completions.create(**params)
+            async for chunk in stream:
+                now = time.perf_counter()
+                # Every chunk carries the server-assigned request id. Capture
+                # it once (the first non-None value) so callers can later
+                # correlate per-request perf metrics drained from
+                # ``/perf_metrics`` with the GenerationTask that issued them.
+                if request_id is None:
+                    cid = getattr(chunk, "id", None)
+                    if cid is not None:
+                        request_id = cid
+                for choice in (chunk.choices or []):
+                    delta_text = getattr(choice, "text", "") or ""
+                    delta_token_ids = getattr(choice, "token_ids", None)
+                    if ttft_s is None and (delta_text or delta_token_ids):
+                        ttft_s = now - t_start
+                    if delta_text:
+                        text_parts.append(delta_text)
+                    if delta_token_ids:
+                        token_ids_acc.extend(delta_token_ids)
+                    delta_logprobs = getattr(choice, "logprobs", None)
+                    if delta_logprobs is not None:
+                        logprobs_acc.append(delta_logprobs)
+                    fr = getattr(choice, "finish_reason", None)
+                    if fr is not None:
+                        finish_reason = fr
+                usage = getattr(chunk, "usage", None)
+                if usage is not None:
+                    ct = getattr(usage, "completion_tokens", None)
+                    pt = getattr(usage, "prompt_tokens", None)
+                    if ct is not None:
+                        usage_completion_tokens = int(ct)
+                    if pt is not None:
+                        usage_prompt_tokens = int(pt)
+            latency_s = time.perf_counter() - t_start
+
+            task.output_str = "".join(text_parts)
+            task.output_tokens = token_ids_acc if token_ids_acc else None
+            task.finish_reason = finish_reason
+            task.logprobs = logprobs_acc if logprobs_acc else None
+            task.ttft_s = ttft_s
+            task.latency_s = latency_s
+            task.usage_completion_tokens = usage_completion_tokens
+            task.usage_prompt_tokens = usage_prompt_tokens
+            task.request_id = request_id
 
             return TaskStatus.SUCCESS
 
         except Exception as e:
-            # Handle errors
             print('Openai client get exception: ' + str(e))
             return TaskStatus.WORKER_EXECEPTION
 
@@ -163,20 +394,36 @@ async def chat_handler(self, task: ChatTask) -> TaskStatus:
         params["model"] = self.model
         if task.tools is not None:
             params["tools"] = [tool.to_dict() for tool in task.tools]
+        task.llm_request_params = self._request_params_for_trace(params)
 
         try:
             response = await self.async_client.chat.completions.create(**params)
-            task.finish_reason = response.choices[0].finish_reason
-            content = response.choices[0].message.content
-            reasoning = response.choices[0].message.reasoning
-            reasoning_content = response.choices[0].message.reasoning_content
-            tool_calls = response.choices[0].message.tool_calls
+            finish_reason = response.choices[0].finish_reason
+            task.finish_reason = finish_reason
+            message = response.choices[0].message
+            content = self._get_response_field(message, "content")
+            reasoning = self._get_response_field(message, "reasoning")
+            reasoning_content = self._get_response_field(
+                message, "reasoning_content")
+            if reasoning_content is None:
+                reasoning_content = self._reasoning_content_from_thinking_blocks(
+                    message)
+            tool_calls = self._get_response_field(message, "tool_calls")
             task.messages.append(
                 AssistantMessage(content, reasoning, reasoning_content,
-                                 tool_calls))
+                                 tool_calls, finish_reason))
             if task.enable_token_counting:
-                task.prompt_tokens_num = response.usage.prompt_tokens
-                task.completion_tokens_num = response.usage.completion_tokens
+                usage = self._get_response_field(response, "usage")
+                if usage is not None:
+                    task.prompt_tokens_num = self._get_response_field(
+                        usage, "prompt_tokens") or 0
+                    task.completion_tokens_num = self._get_response_field(
+                        usage, "completion_tokens") or 0
+                    details = self._get_response_field(
+                        usage, "completion_tokens_details")
+                    if details is not None:
+                        task.reasoning_tokens_num = self._get_response_field(
+                            details, "reasoning_tokens") or 0
 
             return TaskStatus.SUCCESS
 
@@ -189,36 +436,77 @@ async def drop_kv_cache_handler(self, task: DropKVCacheTask) -> TaskStatus:
         if not self.kv_cache_hint_enabled:
             return TaskStatus.SUCCESS
 
-        base_url = str(self.async_client.base_url).rstrip("/")
-        if base_url.endswith("/v1"):
-            base_url = base_url[:-3]
-        url = base_url + "/_resource_governor/truncate"
+        params = self.convert_task_params(task.chat_task)
+        params["messages"] = task.chat_task.messages_to_dict_content()
+        params["model"] = self.model
+        if task.chat_task.tools is not None:
+            params["tools"] = [tool.to_dict() for tool in task.chat_task.tools]
+
+        response = await self.async_client.create_kv_cache_hint(task, params)
+        if response.status_code != 200:
+            return TaskStatus.WORKER_EXECEPTION
+        return TaskStatus.SUCCESS
 
+    async def tokenize_handler(self, task: TokenizeTask) -> TaskStatus:
+        base_url = str(self.async_client.base_url).rstrip("/")
+        # The tokenize endpoint is served under /_internal (not part of the
+        # OpenAI-compatible /v1 surface), so strip a trailing /v1 if present.
+        root_url = base_url[:-3] if base_url.endswith("/v1") else base_url
+        candidate_urls = [f"{root_url}/_internal/tokenize"]
+        failures = []
+        task.tokenize_error = None
         headers = {}
         if self.async_client.api_key is not None:
             headers["Authorization"] = f"Bearer {self.async_client.api_key}"
-
         payload = {
-            "model":
-            self.model,
-            "messages":
-            [message.to_dict() for message in task.chat_task.messages],
-            "messages_to_retain":
-            [message.to_dict() for message in task.messages_to_retain],
+            "prompt": task.content,
+            # Include model for multi-model routers and gateways.
+            "model": self.model,
         }
-        if task.chat_task.tools is not None:
-            payload["tools"] = [tool.to_dict() for tool in task.chat_task.tools]
-
-        async with httpx.AsyncClient() as client:
-            response = await client.post(url, json=payload, headers=headers)
-        if response.status_code != 200:
+        try:
+            async with httpx.AsyncClient() as client:
+                for url in candidate_urls:
+                    try:
+                        response = await client.post(url,
+                                                     json=payload,
+                                                     headers=headers)
+                    except Exception as e:
+                        failures.append(f"{url} raised {type(e).__name__}: {e}")
+                        continue
+                    if response.status_code != 200:
+                        text_preview = response.text[:200].replace("\n", " ")
+                        failures.append(
+                            f"{url} returned {response.status_code}: {text_preview}"
+                        )
+                        continue
+                    body = response.json()
+                    if "count" in body:
+                        task.token_count = body.get("count", 0)
+                        task.tokenize_error = None
+                    elif "tokens" in body and isinstance(body["tokens"], list):
+                        task.token_count = len(body["tokens"])
+                        task.tokenize_error = None
+                    else:
+                        failures.append(
+                            f"{url} returned malformed response keys={list(body.keys())}"
+                        )
+                        continue
+                    return TaskStatus.SUCCESS
+        except Exception as e:
+            task.tokenize_error = f"Tokenize request got exception: {e}"
+            print('Tokenize request got exception: ' + str(e))
             return TaskStatus.WORKER_EXECEPTION
-        return TaskStatus.SUCCESS
+        if failures:
+            task.tokenize_error = "; ".join(failures)
+            print("Tokenize request failed across candidate endpoints: " +
+                  "; ".join(failures))
+        return TaskStatus.WORKER_EXECEPTION
 
     task_handlers = {
         GenerationTask: generation_handler,
         ChatTask: chat_handler,
-        DropKVCacheTask: drop_kv_cache_handler
+        DropKVCacheTask: drop_kv_cache_handler,
+        TokenizeTask: tokenize_handler,
     }
 
 
@@ -289,7 +577,8 @@ def convert_task_params(self, task: GenerationTask):
             top_p=task.top_p,
             top_k=task.top_k,
             return_context_logits=task.return_context_logits,
-            logprobs=task.num_logprobs)
+            logprobs=task.num_logprobs,
+            ignore_eos=task.ignore_eos)
         return sampling_params
 
     async def streaming_generate_helper(self, generate_result, step_at_least,
@@ -367,6 +656,38 @@ def shutdown(self):
     }
 
 
+def _apply_mcp_tool_text_payload(task: MCPCallTask,
+                                 text: Optional[str]) -> None:
+    """If *text* is a Coder-style JSON envelope, set chat content and stdio fields.
+
+    Envelope shape: ``{"content": str, "stdout": str, "stderr": str}`` (from Apiary
+    MCP).  Otherwise *task*.result_str is *text* and stdio fields stay None.
+    """
+    task.result_str = text
+    task.result_stdout = None
+    task.result_stderr = None
+    if not text or not text.lstrip().startswith("{"):
+        return
+    try:
+        payload = json.loads(text)
+    except json.JSONDecodeError:
+        return
+    if not isinstance(payload, dict):
+        return
+    if not all(k in payload for k in ("content", "stdout", "stderr")):
+        return
+    content = payload["content"]
+    if not isinstance(content, str):
+        return
+    task.result_str = content
+    out = payload.get("stdout")
+    err = payload.get("stderr")
+    task.result_stdout = out if isinstance(
+        out, str) else (str(out) if out is not None else "")
+    task.result_stderr = err if isinstance(
+        err, str) else (str(err) if err is not None else "")
+
+
 class MCPWorker(Worker):
 
     class ToolCall:
@@ -475,9 +796,194 @@ async def call_handler(self, task: MCPCallTask) -> TaskStatus:
             await tool_call.ready.wait()
             result = tool_call.result
             if result is not None:
-                task.result_str = result
+                _apply_mcp_tool_text_payload(task, result)
                 break
 
         return TaskStatus.SUCCESS
 
     task_handlers = {MCPCallTask: call_handler}
+
+
+class ApiaryMCPWorker(Worker):
+    """MCP worker with per-scope SSE connections for Apiary sandbox isolation.
+
+    Unlike :class:`MCPWorker` which maintains a single shared SSE connection,
+    ``ApiaryMCPWorker`` creates a separate SSE connection (and therefore a
+    separate Apiary sandbox session) for each :class:`ExecutionScope`.
+    The scope is read from the :data:`current_scope` ContextVar that
+    :class:`ScaffoldingLlm` sets automatically for every request and
+    parallel branch.  Connections are released when the scope ends.
+
+    Usage::
+
+        worker = ApiaryMCPWorker("http://localhost:8082/sse")
+        # No init_in_asyncio_event_loop() needed -- connections are lazy.
+    """
+
+    class _ToolCall:
+
+        def __init__(self, tool_name: str, args: dict):
+            self.tool_name = tool_name
+            self.args = args
+            self.ready = asyncio.Event()
+            self.result: Optional[str] = None
+            self.error: bool = False
+
+        def set_result(self, result: Optional[str], *, error: bool = False):
+            self.result = result
+            self.error = error
+            self.ready.set()
+
+    class _ConnState:
+        __slots__ = ("queue", "task", "ready")
+
+        def __init__(self, queue: asyncio.Queue, task: asyncio.Task,
+                     ready: asyncio.Event):
+            self.queue = queue
+            self.task = task
+            self.ready = ready
+
+    def __init__(self, base_url: str, max_connections: int = 200):
+        self.base_url = base_url.rstrip("/")
+        self._max_connections = max_connections
+        self._conns: dict[str, ApiaryMCPWorker._ConnState] = {}
+        self._scope_params: dict[str, dict[str, str | list[str]]] = {}
+        # Lazy-init for asyncio primitives (must be created inside the loop).
+        self._lock: Optional[asyncio.Lock] = None
+        self._sem: Optional[asyncio.Semaphore] = None
+
+    def _ensure_primitives(self):
+        if self._lock is None:
+            self._lock = asyncio.Lock()
+            self._sem = asyncio.Semaphore(self._max_connections)
+
+    def set_scope_params(self, request_id: str,
+                         **params: str | list[str]) -> None:
+        """Associate extra SSE URL query parameters with *request_id*.
+
+        These parameters are appended to the SSE URL when the connection
+        for this request (or any of its child scopes) is created.  Call
+        this **after** :meth:`ScaffoldingLlm.generate_async` returns, using
+        ``result.id`` as the *request_id*.
+
+        Values may be strings or lists of strings.  List values are
+        emitted as repeated query parameters (e.g.
+        ``base_image=/p1&base_image=/p2``).
+
+        Typical usage for SWE-bench::
+
+            result = llm.generate_async(prompt)
+            mcp_worker.set_scope_params(
+                result.id,
+                base_image=["/layer/base", "/layer/top"],
+            )
+        """
+        self._scope_params[request_id] = params
+
+    async def _conn_loop(self, url: str, queue: asyncio.Queue,
+                         ready: asyncio.Event):
+        try:
+            async with sse_client(url) as streams:
+                async with ClientSession(*streams) as session:
+                    await session.initialize()
+                    ready.set()
+                    while True:
+                        tc = await queue.get()
+                        if tc is None:
+                            return
+                        try:
+                            resp = await session.call_tool(
+                                tc.tool_name, tc.args)
+                            tc.set_result(resp.content[0].text)
+                        except Exception as exc:
+                            tc.set_result(f"Error: {exc}", error=True)
+        except Exception:
+            ready.set()  # unblock waiters even on connection failure
+
+    @staticmethod
+    def _root_request_id(scope_id: str) -> str:
+        """Extract the root request_id from a scope_id.
+
+        Child scopes have the format ``request_id:branch.path``.
+        """
+        return scope_id.split(":")[0]
+
+    async def _get_conn(self, scope_id: str) -> "_ConnState":
+        self._ensure_primitives()
+        async with self._lock:
+            if scope_id in self._conns:
+                conn = self._conns[scope_id]
+            else:
+                await self._sem.acquire()
+                url = f"{self.base_url}?client_id=coder-{scope_id}"
+                extra = self._scope_params.get(self._root_request_id(scope_id),
+                                               {})
+                if extra:
+                    url += "&" + urlencode(extra, doseq=True)
+                queue: asyncio.Queue = asyncio.Queue()
+                ready = asyncio.Event()
+                task = asyncio.create_task(self._conn_loop(url, queue, ready))
+                conn = self._ConnState(queue=queue, task=task, ready=ready)
+                self._conns[scope_id] = conn
+        await conn.ready.wait()
+        return conn
+
+    async def release_connection(self, scope_id: str) -> None:
+        """Close the SSE connection for *scope_id* and release the slot."""
+        self._ensure_primitives()
+        async with self._lock:
+            conn = self._conns.pop(scope_id, None)
+        if conn is None:
+            return
+        conn.queue.put_nowait(None)
+        try:
+            await asyncio.wait_for(conn.task, timeout=5.0)
+        except (asyncio.TimeoutError, asyncio.CancelledError, Exception):
+            conn.task.cancel()
+        self._sem.release()
+        root_id = self._root_request_id(scope_id)
+        if scope_id == root_id:
+            self._scope_params.pop(root_id, None)
+
+    async def call_handler(self, task: MCPCallTask) -> TaskStatus:
+        from .execution_scope import current_scope
+        scope = current_scope.get()
+        scope_id = scope.scope_id if scope is not None else "default"
+
+        conn = await self._get_conn(scope_id)
+
+        tc = self._ToolCall(task.tool_name, json.loads(task.args))
+        conn.queue.put_nowait(tc)
+        await tc.ready.wait()
+
+        if tc.result is not None:
+            _apply_mcp_tool_text_payload(task, tc.result)
+
+        if tc.error:
+            return TaskStatus.WORKER_EXECEPTION
+        return TaskStatus.SUCCESS
+
+    task_handlers = {MCPCallTask: call_handler}
+
+    async def on_scope_end(self, scope_id: str) -> None:
+        await self.release_connection(scope_id)
+
+    async def async_shutdown(self):
+        """Close all SSE connections and wait for background tasks."""
+        self._ensure_primitives()
+        async with self._lock:
+            ids = list(self._conns.keys())
+        for rid in ids:
+            await self.release_connection(rid)
+
+    def shutdown(self):
+        try:
+            loop = asyncio.get_event_loop()
+            if loop.is_running():
+                fut = asyncio.run_coroutine_threadsafe(self.async_shutdown(),
+                                                       loop)
+                fut.result(timeout=30)
+            else:
+                loop.run_until_complete(self.async_shutdown())
+        except Exception:
+            pass
diff --git a/tensorrt_llm/serve/openai_protocol.py b/tensorrt_llm/serve/openai_protocol.py
index 3993e0e8168d..ba079d7a4637 100644
--- a/tensorrt_llm/serve/openai_protocol.py
+++ b/tensorrt_llm/serve/openai_protocol.py
@@ -143,6 +143,44 @@ class ModelList(OpenAIBaseModel):
     data: List[ModelCard] = Field(default_factory=list)
 
 
+class TokenizeRequest(OpenAIBaseModel):
+    """Request body for the ``POST /_internal/tokenize`` endpoint.
+
+    Asks the server to encode some text into the token-id sequence its
+    loaded tokenizer would produce, without running any generation.
+
+    Only plain-text ``prompt`` tokenization is supported. A ``messages``
+    path was intentionally left out: to be meaningful it must reuse the full
+    ``/v1/chat/completions`` preprocessing (server chat template, tools,
+    documents, template kwargs, model-type resolution, multimodal handling),
+    otherwise the returned token ids would silently diverge from the actual
+    inference prompt. It can be added once that path is shared.
+
+    Fields:
+        model: Target model name. Accepted for compatibility with
+            multi-model routers but ignored -- the server always tokenizes
+            against its own loaded model.
+        prompt: Plain text to tokenize directly via ``tokenizer.encode``.
+    """
+
+    model: Optional[str] = None
+    prompt: str
+
+
+class TokenizeResponse(OpenAIBaseModel):
+    """Response body for the ``POST /_internal/tokenize`` endpoint.
+
+    Fields:
+        count: Number of tokens in the encoded sequence. Always populated;
+            clients needing only the length can ignore ``tokens``.
+        tokens: The encoded token ids. Kept ``Optional`` so future
+            count-only variants can omit it without breaking the schema.
+    """
+
+    count: int
+    tokens: Optional[List[int]] = None
+
+
 class ResponseFormat(OpenAIBaseModel):
     type: Literal["text", "json", "json_schema", "json_object", "regex", "ebnf",
                   "structural_tag"]
@@ -1055,6 +1093,36 @@ class KVCacheTruncateRequest(OpenAIBaseModel):
     tool_choice: Optional[str] = None
 
 
+class KVCacheTruncateTokensRequest(OpenAIBaseModel):
+    """Token-level analog of :class:`KVCacheTruncateRequest`.
+
+    Posted to the ``/_control/kv_cache/truncate_tokens`` endpoint. Bypasses
+    the chat-template tokenization path entirely: callers (e.g.
+    trace replay) that already operate on raw token ids hand the server a
+    batch of full token-id sequences plus the prefix length to retain for
+    each, and the server trims the corresponding KV-cache blocks in the
+    radix tree. Each ``prefixes[i]`` becomes one
+    :class:`tensorrt_llm.executor.request.TruncateKVCacheRequest` on the
+    executor's KV-cache control queue, so one batched HTTP request fans out
+    into N atomic per-prefix radix-tree mutations while paying a single
+    network round-trip.
+
+    Fields:
+        model: Target model name. Accepted for router compatibility but
+            ignored -- the server uses its own loaded model.
+        prefixes: Batch of full token-id sequences. Each entry is one
+            cached prefix whose KV-cache blocks should be truncated.
+        num_tokens_to_keep: Per-prefix number of leading tokens to retain,
+            parallel to ``prefixes`` (``num_tokens_to_keep[i]`` applies to
+            ``prefixes[i]``). Blocks beyond this length are dropped from the
+            radix tree.
+    """
+
+    model: Optional[str] = None
+    prefixes: List[List[int]]
+    num_tokens_to_keep: List[int]
+
+
 ResponseInputOutputItem: TypeAlias = Union[ResponseInputItemParam,
                                            ResponseReasoningItem,
                                            ResponseFunctionToolCall]
diff --git a/tensorrt_llm/serve/openai_server.py b/tensorrt_llm/serve/openai_server.py
index d03dbab494da..b8cf77674883 100644
--- a/tensorrt_llm/serve/openai_server.py
+++ b/tensorrt_llm/serve/openai_server.py
@@ -72,8 +72,9 @@
     EmbeddingResponseData, EmbeddingUsageInfo, ErrorResponse,
     ImageGenerationRequest, ImageGenerationResponse, ImageObject,
     MemoryUpdateRequest, ModelCard, ModelList, PromptTokensDetails,
-    ResponseFormat, ResponsesRequest, ResponsesResponse, UpdateWeightsRequest,
-    UsageInfo, ensure_request_chat_template_allowed, to_llm_conversation_params,
+    ResponseFormat, ResponsesRequest, ResponsesResponse, TokenizeRequest,
+    TokenizeResponse, UpdateWeightsRequest, UsageInfo,
+    ensure_request_chat_template_allowed, to_llm_conversation_params,
     to_llm_disaggregated_params)
 from tensorrt_llm.serve.openai_video_routes import _VideoRoutesMixin
 from tensorrt_llm.serve.postprocess_handlers import (
@@ -857,6 +858,9 @@ def register_routes(self):
         self.app.add_api_route('/v1/responses/{response_id}',
                                self.openai_responses_delete_response,
                                methods=["DELETE"])
+        self.app.add_api_route("/_internal/tokenize",
+                               self.tokenize,
+                               methods=["POST"])
 
         # RL-only endpoints
         self.app.add_api_route("/release_memory",
@@ -2301,6 +2305,17 @@ async def openai_responses_delete_response(
             "deleted": True
         })
 
+    async def tokenize(self, request: TokenizeRequest) -> JSONResponse:
+        try:
+            token_ids = self.tokenizer.encode(request.prompt)
+            response = TokenizeResponse(count=len(token_ids), tokens=token_ids)
+            return JSONResponse(content=response.model_dump())
+        except Exception as e:
+            return self.create_error_response(
+                message=str(e),
+                err_type="InvalidRequestError",
+                status_code=HTTPStatus.BAD_REQUEST)
+
     async def release_memory(self,
                              request: MemoryUpdateRequest) -> JSONResponse:
         assert isinstance(
diff --git a/tensorrt_llm/serve/resource_governor.py b/tensorrt_llm/serve/resource_governor.py
index 7b658056422f..9b475a97ad8d 100644
--- a/tensorrt_llm/serve/resource_governor.py
+++ b/tensorrt_llm/serve/resource_governor.py
@@ -32,6 +32,7 @@
 from tensorrt_llm.serve.chat_utils import parse_chat_messages_coroutines
 from tensorrt_llm.serve.openai_protocol import (
     KVCacheTruncateRequest,
+    KVCacheTruncateTokensRequest,
     ensure_request_chat_template_allowed,
 )
 
@@ -72,6 +73,19 @@ def register_routes(self, app: FastAPI):
         else:
             handler = self._truncate_kv_cache
         app.add_api_route("/_resource_governor/truncate", handler, methods=["POST"])
+        # Alias under the new ``/_control/kv_cache/*`` namespace; kept
+        # alongside the legacy ``/_resource_governor/*`` route until all
+        # external callers are migrated.
+        app.add_api_route("/_control/kv_cache/truncate", handler, methods=["POST"])
+        # Token-level variant for callers that already have raw token ids
+        # (trace replay, synthetic-prompt benchmarks).  Skips the chat
+        # template path so the radix-tree walk targets the exact byte
+        # sequence the caller previously sent on a generation request.
+        app.add_api_route(
+            "/_control/kv_cache/truncate_tokens",
+            self._truncate_kv_cache_tokens,
+            methods=["POST"],
+        )
 
     def _create_error_response(self, message: str, status_code: int) -> JSONResponse:
         return JSONResponse(content={"error": message}, status_code=status_code)
@@ -203,3 +217,50 @@ async def _truncate_kv_cache_harmony(self, request: KVCacheTruncateRequest) -> R
         except Exception as e:
             logger.error(traceback.format_exc())
             return self._create_error_response(str(e), HTTPStatus.INTERNAL_SERVER_ERROR)
+
+    async def _truncate_kv_cache_tokens(self, request: KVCacheTruncateTokensRequest) -> Response:
+        """Handle :class:`KVCacheTruncateTokensRequest` — token-level truncate variant.
+
+        Used by trace replay.
+
+        Validates the parallel arrays, then posts one
+        :class:`TruncateKVCacheRequest` per ``(prefix, keep)`` pair onto
+        the executor's KV cache control queue.  Does not touch the chat
+        template, the tokenizer, or the harmony adapter — the radix-tree
+        lookup hashes the prefix bytes the caller already sent on a prior
+        generation request.
+        """
+        try:
+            prefixes = request.prefixes or []
+            keeps = request.num_tokens_to_keep or []
+            if len(prefixes) != len(keeps):
+                return self._create_error_response(
+                    f"len(prefixes)={len(prefixes)} != len(num_tokens_to_keep)={len(keeps)}",
+                    HTTPStatus.BAD_REQUEST,
+                )
+            for i, (prefix, keep) in enumerate(zip(prefixes, keeps)):
+                if keep < 0 or keep > len(prefix):
+                    return self._create_error_response(
+                        f"prefixes[{i}]: num_tokens_to_keep={keep} out of range [0, {len(prefix)}]",
+                        HTTPStatus.BAD_REQUEST,
+                    )
+
+            for prefix, keep in zip(prefixes, keeps):
+                # Only ``len(messages_to_retain)`` is read by
+                # ``KVCacheManager.truncate_blocks`` (it uses the count as
+                # the tokens-to-keep cap on the prefix walk), so the
+                # contents of ``messages_to_retain`` are immaterial here.
+                # Slicing ``prefix[:keep]`` keeps the values consistent
+                # for any future consumer that decides to inspect them.
+                err = self._put_or_unavailable(
+                    TruncateKVCacheRequest(
+                        messages_to_retain=list(prefix[:keep]),
+                        messages=list(prefix),
+                    )
+                )
+                if err is not None:
+                    return err
+            return Response(status_code=200)
+        except Exception as e:
+            logger.error(traceback.format_exc())
+            return self._create_error_response(str(e), HTTPStatus.INTERNAL_SERVER_ERROR)
diff --git a/tests/unittest/llmapi/apps/_test_openai_misc.py b/tests/unittest/llmapi/apps/_test_openai_misc.py
index d4a8ae5e3a95..1f34479dd3a6 100644
--- a/tests/unittest/llmapi/apps/_test_openai_misc.py
+++ b/tests/unittest/llmapi/apps/_test_openai_misc.py
@@ -99,6 +99,21 @@ def test_model(client: openai.OpenAI, model_name: str):
     assert model.id == model_name.split('/')[-1]
 
 
+def test_tokenize(server: RemoteOpenAIServer):
+    tokenize_url = server.url_for("_internal", "tokenize")
+
+    # prompt path: encode raw text directly.
+    prompt_resp = requests.post(tokenize_url, json={"prompt": "Hello, world!"})
+    assert prompt_resp.status_code == 200
+    prompt_body = prompt_resp.json()
+    assert prompt_body["count"] == len(prompt_body["tokens"]) > 0
+
+    # prompt is required; an empty body fails request-model validation. The
+    # server's RequestValidationError handler renders that as 400 (not the
+    # FastAPI default 422) to match the shared {"error": ...} envelope.
+    assert requests.post(tokenize_url, json={}).status_code == 400
+
+
 @pytest.mark.parametrize("use_beam_search", [False, True])
 # reference: https://github.com/vllm-project/vllm/blob/44f990515b124272f87954fc763d90697d8aa1db/tests/entrypoints/openai/test_basic.py#L123
 @pytest.mark.asyncio
diff --git a/tests/unittest/llmapi/apps/test_openai_tokenize.py b/tests/unittest/llmapi/apps/test_openai_tokenize.py
new file mode 100644
index 000000000000..2c57f5407ca0
--- /dev/null
+++ b/tests/unittest/llmapi/apps/test_openai_tokenize.py
@@ -0,0 +1,35 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Unit tests for the ``TokenizeRequest`` schema.
+
+The ``/_internal/tokenize`` endpoint only tokenizes a plain-text ``prompt``;
+it is the required field of the request. ``messages`` is intentionally
+unsupported (see ``TokenizeRequest`` docstring), so it must be rejected.
+"""
+
+import pytest
+from pydantic import ValidationError
+
+from tensorrt_llm.serve.openai_protocol import TokenizeRequest
+
+
+def test_missing_prompt_rejected():
+    with pytest.raises(ValidationError):
+        TokenizeRequest()
+
+
+def test_messages_rejected():
+    with pytest.raises(ValidationError):
+        TokenizeRequest(messages=[{"role": "user", "content": "hello"}])
diff --git a/tests/unittest/scaffolding/test_mcp_worker.py b/tests/unittest/scaffolding/test_mcp_worker.py
index 56c7f428e379..7faabff62769 100644
--- a/tests/unittest/scaffolding/test_mcp_worker.py
+++ b/tests/unittest/scaffolding/test_mcp_worker.py
@@ -190,6 +190,7 @@ def __init__(self, name: str, arguments: dict):
 
 class ToolCall:
     def __init__(self, name: str, arguments: dict):
+        self.id = f"call_{name}"
         self.function = FunctionCall(name, arguments)