devsper 2.3.0__tar.gz → 2.4.1__tar.gz

{devsper-2.3.0 → devsper-2.4.1}/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.4.1] — 2026-03-31
+
+### Fixed
+
+- **HITL prompt loop + context handoff** — Clarification responses are now reused across subtasks, repeated clarification prompts are deduplicated/capped, and follow-up tasks inherit prior user decisions instead of re-asking equivalent questions.
+- **Run view prompt stability** — Local clarification prompts now pause/resume live rendering cleanly, reducing TUI corruption and preventing hidden/stuck prompts during interactive runs.
+- **Silent-failure propagation** — Agent failures now surface as explicit task failures (instead of empty-success paths), with clearer errors for missing model configuration.
+- **Executor compatibility regression** — Restored `budget_manager` compatibility on the runtime executor path to avoid end-of-run `AttributeError` crashes.
+
+### Changed
+
+- **Research tool routing defaults** — Tool selection now biases web-first for research/business discovery tasks when no local dataset path is provided.
+- **Export readability + content coverage** — Run export now backfills task outputs from tool traces when direct task result payloads are missing, and includes richer run details in markdown/html/latex/docx outputs.
+- **Duration formatting** — CLI run summary and export outputs now prefer `HH:MM:SS` format.
+- **Telemetry noise control** — Console span export is now opt-in (`DEVSPER_OTEL_CONSOLE=1`) to keep interactive TUI output clean by default.
+- **Auto-export workflow** — Added config-driven post-run export option (`[export] auto_export_on_run`) with selectable output format.
+
+## [2.4.0] — 2026-03-31
+
+### Added
+
+- **Distributed runtime extensions** — Added modular runtime components for distributed orchestration: `AgentPool`, `ModelRouter`, `SpeculativePlanner`, `HITLManager`, `ExecutionGraph` worker assignment tracking, plus distributed wrappers (`distributed/controller.py`, `distributed/worker_runtime.py`).
+- **Runtime architecture documentation** — Expanded runtime docs with distributed architecture, worker/controller lifecycle, speculative execution flow, and HITL lifecycle details.
+- **Tool execution hardening** — Upgraded runtime tool runner with bounded parallelism, dependency-aware batching, per-call timeout isolation, and cancellation support.
+
+### Changed
+
+- **Executor orchestration** — Runtime executor now supports agent-pool-backed execution, model routing integration, speculative follow-up scheduling hooks, and improved cancellation/backpressure behavior.
+- **Prompt/token efficiency** — Tool schema injection in agent prompts was compressed to reduce runtime token overhead in tool-enabled turns.
+- **Homepage and release communication** — Updated README homepage with v2.4.0 release CTA and an architecture upgrade blog entry for this release.
+
 ## [2.3.0] — 2026-03-30
 
 ### Added

{devsper-2.3.0 → devsper-2.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devsper
-Version: 2.3.0
+Version: 2.4.1
 Summary: Orchestrate distributed swarms of AI agents that collaboratively solve complex tasks.
 Project-URL: Homepage, https://github.com/devsper-com/runtime
 Project-URL: Documentation, https://docs.devsper.com

devsper-2.4.1/devsper/README.md

@@ -0,0 +1,148 @@
+# Devsper Runtime Core
+
+Devsper runtime is built as a modular orchestration core with bounded concurrency, dynamic DAG mutation, and event-stream-driven observability.
+
+## Runtime Architecture Diagram
+
+```text
+User Task
+   |
+   v
+Swarm.run()
+   |
+   v
+Planner -> Scheduler (DAG)
+   |
+   v
+Runtime Executor ------------------------------+
+   |                                           |
+   +-> RuntimeStateManager                     |
+   +-> ExecutionGraph                          |
+   +-> RuntimeEventStream -> EventLog -> SSE  |
+   +-> TaskRunner                              |
+         +-> AgentRunner (optional stream-tool loop)
+               +-> Agent
+               +-> ToolRunner / tools.tool_runner
+```
+
+## Core Components
+
+- `swarm/swarm.py`
+  - Public entrypoint (`Swarm`), config/wiring, planning and execution bootstrap.
+- `runtime/executor.py`
+  - Event-driven scheduler loop, bounded parallel execution, cancellation propagation, dynamic task injection.
+- `runtime/state_manager.py`
+  - Concurrency-safe task state transitions and runtime DAG mutation entrypoint.
+- `runtime/execution_graph.py`
+  - Execution graph with lineage, edges, attempts, and status transitions.
+- `runtime/planner.py`
+  - Runtime wrapper for dynamic planner expansion and parent-child lineage.
+- `runtime/task_runner.py`
+  - Task lifecycle orchestration with scoped retries and fallback model handling.
+- `runtime/agent_runner.py`
+  - Async agent wrapper with optional streaming tool invocation loop.
+- `runtime/tool_runner.py`
+  - Parallel tool scheduler with bounded concurrency, dependency-aware batching, timeout, and cancellation.
+- `runtime/event_stream.py`
+  - In-process stream with queue backpressure policy (drop-oldest on overflow).
+- `runtime/retry.py`
+  - Retry scopes (`tool`, `agent`, `task`, `model_fallback`) and backoff policies.
+
+## Execution Lifecycle
+
+1. `Swarm.run()` creates root task, plans subtasks, and builds scheduler DAG.
+2. Executor emits `EXECUTOR_STARTED` and begins bounded task dispatch.
+3. Ready tasks transition to running through `RuntimeStateManager`.
+4. `TaskRunner` executes with scoped retries.
+5. `AgentRunner` may invoke tools (normal or streaming tool loop).
+6. Task completion/failure updates scheduler + execution graph.
+7. Adaptive mode can inject follow-up tasks at runtime.
+8. Executor emits `EXECUTOR_FINISHED` and `RUN_COMPLETED`.
+
+## Tool Calling Flow
+
+1. Agent determines tool intent from model output.
+2. Tool calls are parsed and scheduled.
+3. `ToolRunner.run_many(...)` executes calls in parallel with:
+   - `max_concurrency` semaphore
+   - dependency constraints (`depends_on`)
+   - per-call timeouts
+   - cancellation checks
+4. Results are isolated per call and fed back into agent loop.
+
+## Planner Flow
+
+1. Initial decomposition by `swarm/planner.py`.
+2. Runtime execution completes a task.
+3. `RuntimePlanner.expand(...)` optionally creates follow-up tasks.
+4. `RuntimeStateManager.add_tasks(...)` mutates DAG safely.
+5. `ExecutionGraph` records lineage from parent task.
+
+## Concurrency Model
+
+- Bounded executor workers (`worker_count`).
+- Bounded tool concurrency (`ToolRunner` semaphore).
+- Queue backpressure in event streaming (`max_queue_size` with controlled dropping).
+- Cooperative pause/resume and cancellation propagation across runtime loops.
+- Lock-guarded scheduler mutations via `RuntimeStateManager`.
+
+## Distributed Runtime Architecture
+
+```text
+Controller
+   |
+   v
+Worker Pool
+   |
+   v
+Worker Runtime
+   |
+   v
+Runtime Executor
+   |
+   v
+Agent Pool
+   |
+   v
+Tool Runner
+```
+
+- `distributed/controller.py`
+  - Worker registry, health state, load-aware assignment, reassignment hooks.
+- `distributed/worker_runtime.py`
+  - Worker-local runtime composition: `Executor`, `AgentPool`, `ModelRouter`, `ToolRunner`.
+- Existing multi-node transport/control remains in `nodes/controller.py` and `nodes/worker.py`.
+
+## Worker Lifecycle
+
+1. Worker registers with controller.
+2. Controller assigns tasks based on health and load.
+3. Worker executes task locally through runtime executor stack.
+4. Worker returns completion/failure.
+5. Controller updates worker/task state and reassigns on failure.
+
+## Controller Lifecycle
+
+1. Track worker registration and health.
+2. Assign ready tasks using load-aware strategy.
+3. Handle failures and perform retry/reassignment.
+4. Maintain global execution progress via event/log channels.
+
+## Agent Pool
+
+- `AgentPool` manages reusable agent instances per worker.
+- Supports `acquire_agent`, `release_agent`, `run_agent`, and `run_parallel`.
+- Enables worker-local, concurrent, reuse-based execution.
+
+## Speculative Execution
+
+- `SpeculativePlanner` predicts likely successor tasks.
+- Executor marks/schedules speculative tasks early.
+- Unused speculative branches can be cancelled on dependency failure.
+
+## HITL Flow
+
+1. Agent indicates human input is required.
+2. Runtime emits HITL/clarification event.
+3. Task pauses until response or timeout.
+4. Execution resumes or fails based on response policy.

{devsper-2.3.0 → devsper-2.4.1}/devsper/agents/agent.py

@@ -454,11 +454,24 @@ def _format_tools_section(tools: list | None = None) -> str:
         from devsper.tools.registry import list_tools
 
         tools = list_tools()
+    max_props = 8
     lines = []
     for t in tools:
         schema = getattr(t, "input_schema", None) or getattr(t, "schema", {}) or {}
+        schema_type = schema.get("type", "object")
+        required = schema.get("required", []) or []
+        props = schema.get("properties", {}) if isinstance(schema.get("properties", {}), dict) else {}
+        compact_props: dict[str, dict] = {}
+        for key in list(props.keys())[:max_props]:
+            p = props.get(key, {}) or {}
+            compact_props[key] = {"type": p.get("type", "string")}
+        compact_schema = {
+            "type": schema_type,
+            "required": required[:max_props],
+            "properties": compact_props,
+        }
         lines.append(f"- {t.name}: {t.description}")
-        lines.append(f"  input_schema: {json.dumps(schema)}")
+        lines.append(f"  input_schema: {json.dumps(compact_schema, separators=(',', ':'))}")
     return "\n".join(lines)
 
 
@@ -581,6 +594,176 @@ class Agent:
         self.audit_logger = audit_logger
         self.audit_run_id = audit_run_id or ""
         self.clarification_requester = None  # set by executor for human-in-the-loop
+        self._hitl_response_cache: dict[str, dict] = {}
+        self._hitl_prompt_counts: dict[str, int] = {}
+        self._hitl_shared_answers: dict[str, str] = {}
+        self._hitl_shared_facts: list[str] = []
+        try:
+            self._hitl_max_prompts_per_task = int(
+                str(os.environ.get("DEVSPER_HITL_MAX_PROMPTS_PER_TASK", "1")).strip()
+                or "1"
+            )
+        except Exception:
+            self._hitl_max_prompts_per_task = 1
+        self._hitl_max_prompts_per_task = max(0, self._hitl_max_prompts_per_task)
+
+    def _default_answer_for_field(self, field: ClarificationField) -> object:
+        prior = self._find_prior_hitl_answer(field.question)
+        if prior:
+            return prior
+        if field.default is not None and str(field.default).strip() != "":
+            return field.default
+        ftype = str(field.type or "text")
+        options = field.options or []
+        if ftype == "confirm":
+            return True
+        if ftype == "multi_select":
+            return [options[0]] if options else []
+        if ftype == "rank":
+            return options
+        if ftype == "mcq":
+            return options[0] if options else "Proceed with best-effort defaults"
+        return "Proceed with best-effort defaults"
+
+    @staticmethod
+    def _normalize_question(text: str) -> str:
+        t = re.sub(r"[^a-z0-9\s]+", " ", (text or "").lower())
+        return re.sub(r"\s+", " ", t).strip()
+
+    def _find_prior_hitl_answer(self, question: str) -> str | None:
+        qn = self._normalize_question(question)
+        if not qn:
+            return None
+        if qn in self._hitl_shared_answers:
+            return self._hitl_shared_answers[qn]
+        q_tokens = {t for t in qn.split() if len(t) > 2}
+        if not q_tokens:
+            return None
+        best_overlap = 0
+        best_answer: str | None = None
+        for prev_qn, prev_answer in self._hitl_shared_answers.items():
+            p_tokens = {t for t in prev_qn.split() if len(t) > 2}
+            overlap = len(q_tokens.intersection(p_tokens))
+            if overlap >= 3 and overlap > best_overlap:
+                best_overlap = overlap
+                best_answer = prev_answer
+        return best_answer
+
+    def _record_hitl_answers(self, answers: dict[str, object]) -> None:
+        for question, answer in (answers or {}).items():
+            qn = self._normalize_question(str(question))
+            if not qn:
+                continue
+            answer_text = str(answer)
+            self._hitl_shared_answers[qn] = answer_text
+            fact = f"- {str(question).strip()}: {answer_text}"
+            if fact not in self._hitl_shared_facts:
+                self._hitl_shared_facts.append(fact)
+
+    def _should_auto_web_collection(
+        self,
+        request: AgentRequest,
+        tool_args: dict,
+        fields: list[ClarificationField],
+    ) -> bool:
+        prior_answers_text = " ".join(self._hitl_shared_answers.values()).lower()
+        prior_facts_text = " ".join(self._hitl_shared_facts).lower()
+        topic = " ".join(
+            [
+                str(self.user_task or ""),
+                str(getattr(request.task, "description", "") or ""),
+                str(tool_args.get("context") or ""),
+                " ".join(f.question for f in fields),
+                prior_answers_text,
+                prior_facts_text,
+            ]
+        ).lower()
+        # If this is clearly a research/data-collection workflow asking for local datasets,
+        # default to web/public-source collection to avoid blocking the run.
+        needs_dataset_input = any(
+            token in topic
+            for token in (
+                "dataset",
+                "csv",
+                "upload",
+                "file",
+                "local path",
+                "paste",
+                "provide the data",
+                "provide the dataset",
+            )
+        )
+        research_like = any(
+            token in topic
+            for token in (
+                "research",
+                "public source",
+                "web",
+                "openai business",
+                "data collection",
+                "comprehensive search",
+                "business aspect",
+            )
+        )
+        prior_prefers_web = any(
+            token in topic
+            for token in (
+                "public urls",
+                "public url",
+                "public-source",
+                "public source",
+                "web collection",
+                "curated list",
+                "crawl",
+                "fetch",
+                "url",
+            )
+        )
+        return needs_dataset_input and (research_like or prior_prefers_web)
+
+    def _auto_web_collection_answers(
+        self,
+        fields: list[ClarificationField],
+    ) -> dict[str, object]:
+        answers: dict[str, object] = {}
+        for f in fields:
+            q = (f.question or "").lower()
+            opts = [str(o) for o in (f.options or [])]
+            # Prefer choices indicating web/public/source fetching.
+            preferred = None
+            for opt in opts:
+                ol = opt.lower()
+                if any(
+                    t in ol
+                    for t in (
+                        "web",
+                        "public",
+                        "url",
+                        "crawl",
+                        "fetch",
+                        "curated list",
+                        "propose",
+                    )
+                ):
+                    preferred = opt
+                    break
+            if preferred is not None:
+                answers[f.question] = preferred
+                continue
+            # If there is no explicit web/public option, avoid blocking on local file uploads.
+            if any(t in q for t in ("dataset", "profile", "csv", "file", "path")):
+                template_opt = next(
+                    (o for o in opts if any(k in o.lower() for k in ("template", "generic", "sample", "synthetic"))),
+                    None,
+                )
+                if template_opt is not None:
+                    answers[f.question] = template_opt
+                    continue
+            if "how many" in q or "count" in q or "limit" in q:
+                answers[f.question] = "Up to 50 public URLs"
+                continue
+            answers[f.question] = self._default_answer_for_field(f)
+        return answers
 
     def run(self, request: AgentRequest) -> AgentResponse:
         """Stateless run: all context in AgentRequest, all output in AgentResponse."""
@@ -757,6 +940,12 @@ class Agent:
             message_bus_section = self.message_bus.get_context_sync(task.id) or ""
         if message_bus_section:
             memory_section = (memory_section + "\n\n" + message_bus_section).strip()
+        if self._hitl_shared_facts:
+            memory_section = (
+                memory_section
+                + "\n\nUSER CLARIFICATIONS (APPLY THESE PREFERENCES ACROSS SUBTASKS)\n"
+                + "\n".join(self._hitl_shared_facts[-20:])
+            ).strip()
         from devsper.agents.roles import get_role_config
 
         role_config = get_role_config(getattr(task, "role", None))
@@ -844,6 +1033,8 @@ class Agent:
                 success=True,
             )
         self.apply_response(task, response)
+        if not response.success:
+            raise RuntimeError(response.error or "Agent run failed")
         return response.result
 
     def _enrich_task(self, task: Task, answers: dict) -> Task:
@@ -1210,6 +1401,57 @@ class Agent:
         if not fields:
             return json.dumps({"error": "hitl.request has no valid fields"})
 
+        if self._should_auto_web_collection(request, tool_args, fields):
+            auto_answers = self._auto_web_collection_answers(fields)
+            self._record_hitl_answers(auto_answers)
+            payload = {
+                "request_id": f"auto-web-{request.task.id}",
+                "skipped": False,
+                "answers": auto_answers,
+                "auto_assumed": True,
+            }
+            return json.dumps(payload)
+
+        task_id = request.task.id
+        used_prompts = int(self._hitl_prompt_counts.get(task_id, 0))
+        if used_prompts >= max(0, self._hitl_max_prompts_per_task):
+            # Fast-path: avoid repeated user interruption after first clarification.
+            auto_answers: dict[str, object] = {}
+            for f in fields:
+                auto_answers[f.question] = self._default_answer_for_field(f)
+            self._record_hitl_answers(auto_answers)
+            payload = {
+                "request_id": f"auto-{task_id}-{used_prompts + 1}",
+                "skipped": False,
+                "answers": auto_answers,
+                "auto_assumed": True,
+            }
+            return json.dumps(payload)
+
+        # Prevent repeated identical prompts in the same task/tool loop.
+        signature_payload = {
+            "task_id": request.task.id,
+            "context": str(tool_args.get("context") or "Need user input"),
+            "fields": [
+                {
+                    "type": f.type,
+                    "question": f.question,
+                    "options": f.options or [],
+                    "default": f.default,
+                    "required": bool(f.required),
+                }
+                for f in fields
+            ],
+        }
+        cache_key = json.dumps(signature_payload, sort_keys=True)
+        cached = self._hitl_response_cache.get(cache_key)
+        if cached is not None:
+            try:
+                self._record_hitl_answers(cached.get("answers") or {})
+            except Exception:
+                pass
+            return json.dumps(cached)
+
         req = ClarificationRequest(
             request_id=str(uuid.uuid4()),
             task_id=request.task.id,
@@ -1220,13 +1462,15 @@ class Agent:
             timeout_seconds=int(tool_args.get("timeout_seconds", 120)),
         )
         resp = requester.request_clarification(req)
-        return json.dumps(
-            {
-                "request_id": req.request_id,
-                "skipped": bool(resp.skipped),
-                "answers": resp.answers or {},
-            }
-        )
+        self._hitl_prompt_counts[task_id] = used_prompts + 1
+        self._record_hitl_answers(resp.answers or {})
+        payload = {
+            "request_id": req.request_id,
+            "skipped": bool(resp.skipped),
+            "answers": resp.answers or {},
+        }
+        self._hitl_response_cache[cache_key] = payload
+        return json.dumps(payload)
 
     def _emit_tool_called_audit(
         self, task_id: str, tool_name: str, result: str

{devsper-2.3.0 → devsper-2.4.1}/devsper/cli/main.py

@@ -130,23 +130,6 @@ def _platform_api_builder():
     return PlatformAPIRequestBuilder(base_url=base_url, org_slug=org, token=token)
 
 
-def _is_platform_default_enabled(args: object) -> bool:
-    if getattr(args, "local_runtime", False):
-        return False
-    # Shadow mode explicitly compares both paths; do not default-route.
-    if getattr(args, "shadow", False):
-        return False
-    if os.environ.get("DEVSPER_PROFILE", "").strip().lower() == "local":
-        return False
-    if str(os.environ.get("DEVSPER_RUN_DEFAULT", "platform")).strip().lower() in {
-        "runtime",
-        "local",
-    }:
-        return False
-    api = _platform_api_builder()
-    return api.enabled()
-
-
 def _extract_platform_run_fields(payload: dict) -> tuple[str, str, int, int, int]:
     status = str(payload.get("status", ""))
     run_id = str(payload.get("run_id", ""))
@@ -181,8 +164,24 @@ def _run_platform_once(task: str, args: object) -> tuple[int, dict, float]:
             task=task, project_id=project_id or "", manifest=manifest
         )
         run_id = str(created.get("run_id", "") or "")
+        poll_interval = float(getattr(args, "platform_poll_interval", 2.0) or 2.0)
+        if poll_interval <= 0:
+            poll_interval = 2.0
+        last_print_status = {"status": ""}
+
+        def _on_update(payload: dict, elapsed: float, changed: bool) -> None:
+            if getattr(args, "quiet", False):
+                return
+            status = str(payload.get("status") or "").strip().lower() or "unknown"
+            if changed or status != last_print_status["status"]:
+                last_print_status["status"] = status
+                print(f"[platform] run_id={run_id} status={status} elapsed={elapsed:.1f}s")
+
         final = api.poll_run(
-            run_id, timeout_seconds=float(getattr(args, "platform_timeout", 180.0))
+            run_id,
+            interval_seconds=poll_interval,
+            timeout_seconds=float(getattr(args, "platform_timeout", 180.0)),
+            on_update=_on_update,
         )
         elapsed = time.time() - started
         return 0, final or {}, elapsed
@@ -251,7 +250,6 @@ def _run_shadow_mode(args: object) -> int:
         task,
         "--quiet",
         "--json",
-        "--local-runtime",
     ]
     local_started = time.time()
     local_proc = subprocess.run(local_cmd, capture_output=True, text=True)
@@ -383,7 +381,7 @@ def _run_platform_connect(args: object) -> int:
 
     print(f"Connected platform: api={api_url} org={org_slug}")
     print(
-        "`devsper run` will now default to platform. Use `--local-runtime` to bypass."
+        "Use `devsper cloud run` to route runs to platform."
     )
     _track_conversion_event("platform_connect_succeeded", {"org": org_slug})
     return 0
@@ -417,13 +415,7 @@ def _run_swarm(args: object) -> int:
     _track_conversion_event("runtime_user_detected", {"command": "run"})
     if getattr(args, "shadow", False):
         return _run_shadow_mode(args)
-    if _is_platform_default_enabled(args):
-        return _run_platform_only(args)
-    if not getattr(args, "local_runtime", False):
-        # Contextual nudge when users are still runtime-only.
-        print(
-            "Tip: run `devsper platform connect` to unlock retries, audit history, billing controls, and team workflows."
-        )
+    print("Running locally...")
     # Local profile fast-path: route through platform pool + local workers.
     if os.environ.get("DEVSPER_PROFILE", "").strip().lower() == "local":
         try:
@@ -436,10 +428,14 @@ def _run_swarm(args: object) -> int:
     from devsper.config import get_config
     from devsper.utils.event_logger import EventLog
     from devsper.swarm.swarm import Swarm
+    from devsper.runtime.executor import Executor
+    from devsper.runtime.agent_runner import AgentRunner
     from devsper.memory.memory_router import MemoryRouter
     from devsper.memory.memory_store import get_default_store
     from devsper.memory.memory_index import MemoryIndex
 
+    _ = (Executor, AgentRunner)
+
     task = getattr(args, "task", "Summarize swarm intelligence in one paragraph.")
     quiet = getattr(args, "quiet", False)
     summary_only = getattr(args, "summary", False)
@@ -625,6 +621,37 @@ def _run_swarm(args: object) -> int:
                 console.print((result or "")[:2000])
                 if (result or "") and len(result) > 2000:
                     console.print("...")
+    try:
+        if getattr(cfg, "export", None) and getattr(cfg.export, "auto_export_on_run", False):
+            from devsper.export.service import ExportOptions, export_all_runs
+
+            ts = int(time.time())
+            out_dir = f".devsper/exports/runs_{ts}"
+            fmt = str(getattr(cfg.export, "format", "docx") or "docx").lower()
+            if fmt == "pdf":
+                pdf_pipeline = "both"
+            else:
+                # docx/html/all still benefit from HTML PDF where available.
+                pdf_pipeline = "html"
+            manifest = export_all_runs(
+                ExportOptions(
+                    output_dir=out_dir,
+                    limit=int(getattr(cfg.export, "limit", 1) or 1),
+                    pdf_pipeline=pdf_pipeline,
+                )
+            )
+            files = manifest.get("files", {}) if isinstance(manifest, dict) else {}
+            print(f"Auto-export complete: {out_dir}")
+            if fmt in {"docx", "all"} and files.get("all_runs_docx"):
+                print(f"DOCX: {files.get('all_runs_docx')}")
+            if fmt in {"html", "all"} and files.get("all_runs_html"):
+                print(f"HTML: {files.get('all_runs_html')}")
+            if fmt in {"pdf", "all"}:
+                pdf_out = (manifest.get("pdf_outputs", {}) or {}).get("html_pdf")
+                if pdf_out:
+                    print(f"PDF: {pdf_out}")
+    except Exception as e:
+        print(f"Auto-export failed: {e}", file=sys.stderr)
     return 0
 
 
@@ -2891,11 +2918,6 @@ Examples:
         action="store_true",
         help="Only print run summary, not task results",
     )
-    run_parser.add_argument(
-        "--local-runtime",
-        action="store_true",
-        help="Force local runtime path even when platform is connected.",
-    )
     run_parser.add_argument(
         "--shadow",
         action="store_true",
@@ -2917,6 +2939,12 @@ Examples:
         default=180.0,
         help="Platform run polling timeout seconds.",
     )
+    run_parser.add_argument(
+        "--platform-poll-interval",
+        type=float,
+        default=2.0,
+        help="Platform polling interval seconds.",
+    )
     run_parser.add_argument(
         "--reporter",
         action="store_true",