seedcode-cli 6.1.5__py3-none-any.whl

seedcode/core/errors.py

@@ -0,0 +1,199 @@
+"""Structured error taxonomy for the SeedCode operator stack.
+
+Machine-readable errors are the contract between the deterministic layers
+(screen, apps, web, memory) and the agent loop: every failure carries a
+stable ``code``, a human-readable message, and whether a retry/recovery is
+plausible. The planner reads ``code`` + ``recoverable``; the user reads
+``message``. Nothing raises a bare string anywhere below the tool surface.
+
+All operator errors derive from :class:`OperatorError` so callers can catch
+the whole family; the historical leaf exceptions (``ComputerError``,
+``BrowserError``, ``SkillError``...) keep their names via aliases where
+existing code depends on them.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+# NOTE: deliberately NOT ``slots=True``. A slotted dataclass replaces the
+# class object, which breaks zero-arg ``super()`` inside ``__post_init__`` for
+# Exception subclasses (``super(type, obj): obj must be an instance or subtype
+# of type``) - every structured error would be unraisable.
+@dataclass
+class OperatorError(Exception):
+    """Base class for every structured operator failure."""
+
+    code: str = "OPERATOR_ERROR"
+    message: str = ""
+    recoverable: bool = False
+    details: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not self.message:
+            object.__setattr__(self, "message", self.code)
+        # Explicit base call: cooperative super() is fragile across the
+        # dataclass/Exception metaclass boundary; Exception.__init__ sets args.
+        Exception.__init__(self, self.message)
+
+    def __str__(self) -> str:  # the model-facing text
+        return self.message
+
+    def to_dict(self) -> dict[str, Any]:
+        """Machine-readable form (planner / error handler / logs)."""
+        return {
+            "error_type": self.code,
+            "message": self.message,
+            "recoverable": self.recoverable,
+            **({"details": self.details} if self.details else {}),
+        }
+
+
+# --- element / screen -----------------------------------------------------------
+class ElementNotFoundError(OperatorError):
+    def __init__(self, message: str = "", **kw: Any) -> None:
+        super().__init__(
+            code="ELEMENT_NOT_FOUND", message=message or "Element not found on screen.",
+            recoverable=True, **kw,
+        )
+
+
+class StaleElementError(OperatorError):
+    """A cached element id no longer resolves — the UI changed under us."""
+
+    def __init__(self, element_id: str = "", **kw: Any) -> None:
+        super().__init__(
+            code="STALE_ELEMENT",
+            message=(
+                f"Element '{element_id or 'reference'}' is stale (the UI changed). "
+                "Re-run the screen query to get a fresh element id."
+            ),
+            recoverable=True,
+            details={"element_id": element_id},
+            **kw,
+        )
+
+
+class ScreenUnavailableError(OperatorError):
+    def __init__(self, message: str = "", **kw: Any) -> None:
+        super().__init__(
+            code="SCREEN_UNAVAILABLE",
+            message=message or "Screen state is unavailable on this machine.",
+            recoverable=False, **kw,
+        )
+
+
+# --- windows / applications -------------------------------------------------------
+class WindowNotFoundError(OperatorError):
+    def __init__(self, message: str = "", **kw: Any) -> None:
+        super().__init__(
+            code="WINDOW_NOT_FOUND", message=message or "No matching window.",
+            recoverable=True, **kw,
+        )
+
+
+class ApplicationNotFoundError(OperatorError):
+    def __init__(self, message: str = "", **kw: Any) -> None:
+        super().__init__(
+            code="APPLICATION_NOT_FOUND",
+            message=message or "Application not found on this machine.",
+            recoverable=True, **kw,
+        )
+
+
+class ApplicationLaunchError(OperatorError):
+    def __init__(self, message: str = "", **kw: Any) -> None:
+        super().__init__(
+            code="APPLICATION_LAUNCH_FAILED",
+            message=message or "Application did not launch.",
+            recoverable=True, **kw,
+        )
+
+
+# --- web ---------------------------------------------------------------------------
+class NavigationError(OperatorError):
+    def __init__(self, message: str = "", **kw: Any) -> None:
+        super().__init__(
+            code="NAVIGATION_FAILED", message=message or "Navigation failed.",
+            recoverable=True, **kw,
+        )
+
+
+class ExtractionError(OperatorError):
+    def __init__(self, message: str = "", **kw: Any) -> None:
+        super().__init__(
+            code="EXTRACTION_FAILED",
+            message=message or "Page extraction failed.",
+            recoverable=True, **kw,
+        )
+
+
+class WebPageNotConnectedError(OperatorError):
+    """No DOM surface (no DevTools) for a requested web extraction."""
+
+    def __init__(self, message: str = "", **kw: Any) -> None:
+        super().__init__(
+            code="WEB_PAGE_NOT_CONNECTED",
+            message=message or (
+                "No DevTools connection to the browser; DOM extraction is "
+                "unavailable. Open the page via open_url first."
+            ),
+            recoverable=True, **kw,
+        )
+
+
+class DownloadBlockedError(OperatorError):
+    """A download was refused by policy (type/size/host)."""
+
+    def __init__(self, message: str = "", **kw: Any) -> None:
+        super().__init__(
+            code="DOWNLOAD_BLOCKED", message=message or "Download refused by policy.",
+            recoverable=False, **kw,
+        )
+
+
+# --- verification / lifecycle / security ---------------------------------------------
+class VerificationError(OperatorError):
+    def __init__(self, message: str = "", **kw: Any) -> None:
+        super().__init__(
+            code="VERIFICATION_FAILED",
+            message=message or "The action did not have the expected effect.",
+            recoverable=True, **kw,
+        )
+
+
+class SecurityError(OperatorError):
+    def __init__(self, message: str = "", **kw: Any) -> None:
+        super().__init__(
+            code="SECURITY_DENIED",
+            message=message or "The action was denied by policy.",
+            recoverable=False, **kw,
+        )
+
+
+# --- historical aliases (existing modules keep their exception names) ---------------
+# These subclass the structured base so both worlds interoperate.
+from ..computer.controller import ComputerError as _ComputerError  # noqa: E402
+from ..computer.browser import BrowserError as _BrowserError  # noqa: E402
+
+
+class ComputerError(OperatorError, _ComputerError):  # type: ignore[misc]
+    """Structured-compatible alias of the controller error."""
+
+    def __init__(self, message: str = "", **kw: Any) -> None:
+        OperatorError.__init__(
+            self, code="COMPUTER_ERROR", message=message, recoverable=True, **kw
+        )
+        Exception.__init__(self, self.message)
+
+
+class BrowserError(OperatorError, _BrowserError):  # type: ignore[misc]
+    """Structured-compatible alias of the browser driver error."""
+
+    def __init__(self, message: str = "", **kw: Any) -> None:
+        OperatorError.__init__(
+            self, code="BROWSER_ERROR", message=message, recoverable=True, **kw
+        )
+        Exception.__init__(self, self.message)

seedcode/core/identity.py

@@ -0,0 +1,66 @@
+"""Seed Code identity layer.
+
+Constructs the system prompt that distinguishes the Seed Code application
+identity from the underlying reasoning engine (Claude, GPT, etc.). Every
+provider must call :func:`build_system_prompt` to prepend the identity layer
+before any conversation.
+"""
+
+from __future__ import annotations
+
+# Centralized identity — edit this ONE place to change how Seed Code introduces itself
+_SEED_CODE_IDENTITY = """You are Seed Code, an AI coding assistant created by Al Shahriar Sowan.
+
+Your purpose is to help users write code, edit projects, debug software, automate development tasks, use local tools, and assist with software engineering.
+
+**Important identity distinctions:**
+
+- You are Seed Code (the application), not the underlying AI model
+- The reasoning engine powering you may be Claude, GPT, Codex, Gemini, Qwen, or another model
+- Always identify yourself as Seed Code first, then mention your current reasoning engine when relevant
+- Never claim to BE Claude, ChatGPT, Gemini, etc. — those are reasoning engines, not your identity
+
+**When asked about your identity:**
+
+- "Who are you?" → "I am Seed Code, an AI coding assistant created by Al Shahriar Sowan. My current reasoning engine is [model]."
+- "Who created you?" or "Who made you?" → "Seed Code was created by Al Shahriar Sowan."
+- "What is Seed Code?" → "Seed Code is an AI coding assistant designed for software development, project automation, and intelligent coding workflows. It supports multiple AI providers while presenting a single unified Seed Code experience."
+- "What model are you using?" → Be truthful: "My current reasoning engine is [model]."
+- "Are you Claude?" or "Are you ChatGPT?" → "I'm Seed Code. For this conversation I'm powered by [model]."
+- "Who owns Seed Code?" → "Seed Code is created and maintained by Al Shahriar Sowan."
+
+Always be truthful about your reasoning engine while maintaining your Seed Code application identity."""
+
+
+def build_system_prompt(provider_label: str, model_id: str) -> str:
+    """Build the complete system prompt with Seed Code identity + reasoning engine context.
+
+    Args:
+        provider_label: Human-readable provider name (e.g., "OpenRouter", "FreeModel Claude")
+        model_id: The model identifier (e.g., "claude-opus-4-8", "gpt-5.5")
+
+    Returns:
+        Complete system prompt starting with Seed Code identity layer
+
+    Example:
+        >>> build_system_prompt("FreeModel Claude", "claude-sonnet-5")
+        'You are Seed Code...\\n\\nYour current reasoning engine: claude-sonnet-5 via FreeModel Claude...'
+    """
+    reasoning_context = (
+        f"\n\nYour current reasoning engine: {model_id} via {provider_label}.\n"
+        f"When users ask about your model or capabilities, mention this truthfully."
+    )
+
+    # Seed Code task instructions (provider-agnostic)
+    task_prompt = """
+
+Be concise and professional. Prefer clear, correct code with short explanations.
+Use markdown fenced code blocks with language hints. Focus on practical, working solutions."""
+
+    # Owner-persisted personality overrides (identity.json). Never model-
+    # written; a model switch re-renders only the reasoning-engine line.
+    from .identity_store import load_identity
+
+    overrides = load_identity().render()
+
+    return _SEED_CODE_IDENTITY + overrides + reasoning_context + task_prompt

seedcode/core/identity_store.py

@@ -0,0 +1,119 @@
+"""SeedCode-owned identity: persistent personality independent of the model.
+
+The identity layer (:mod:`.identity`) hardcodes the baseline personality.
+This module lets the *owner* persist overrides in
+``~/.seedcode/identity.json`` so personality belongs to SeedCode, not to
+any model or prompt-in-flight:
+
+.. code-block:: json
+
+    {
+      "identity": "You are SeedCode, ...",
+      "tone": "concise and professional",
+      "behavior_rules": ["Never claim unverified success."],
+      "interaction_style": ["Answer in the user's language."]
+    }
+
+Rules:
+
+* Overrides are loaded at every prompt build (cheap file read, cached by
+  mtime), so a change takes effect on the next turn without a restart.
+* The model can NEVER write this file: it is owner/user-edited
+  configuration. Nothing in the tool surface exposes it.
+* Model/provider choice has no path into identity: switching models
+  re-renders only the "reasoning engine" line, produced by
+  :func:`build_system_prompt` from live config — personality constants are
+  untouched (pinned by tests).
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from ..utils.helpers import app_dir
+
+
+@dataclass(slots=True)
+class IdentityProfile:
+    """The SeedCode-owned personality configuration."""
+
+    identity: str = ""                     # replaces the baseline identity block
+    tone: str = ""                         # appended as a tone directive
+    behavior_rules: list[str] = field(default_factory=list)
+    interaction_style: list[str] = field(default_factory=list)
+
+    def is_empty(self) -> bool:
+        return not (self.identity or self.tone or self.behavior_rules
+                    or self.interaction_style)
+
+    def render(self) -> str:
+        """The override text injected after the baseline identity."""
+        if self.is_empty():
+            return ""
+        lines: list[str] = []
+        if self.identity:
+            lines.append(self.identity.strip())
+        if self.tone:
+            lines.append(f"\nTone: {self.tone.strip()}")
+        if self.behavior_rules:
+            lines.append("\nBehavior rules:")
+            lines += [f"- {rule}" for rule in self.behavior_rules]
+        if self.interaction_style:
+            lines.append("\nInteraction style:")
+            lines += [f"- {item}" for item in self.interaction_style]
+        return "\n".join(lines).strip()
+
+
+def identity_path() -> Path:
+    """Where the owner's identity overrides live."""
+    return app_dir() / "identity.json"
+
+
+def load_identity() -> IdentityProfile:
+    """Read ``identity.json`` (empty profile when absent/corrupt).
+
+    A corrupt file must never break startup: it degrades to the baseline
+    identity and the problem is logged once.
+    """
+    path = identity_path()
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return IdentityProfile()
+    if not isinstance(data, dict):
+        return IdentityProfile()
+    rules = data.get("behavior_rules")
+    style = data.get("interaction_style")
+    return IdentityProfile(
+        identity=str(data.get("identity", "") or ""),
+        tone=str(data.get("tone", "") or ""),
+        behavior_rules=[str(r) for r in rules] if isinstance(rules, list) else [],
+        interaction_style=[str(s) for s in style] if isinstance(style, list) else [],
+    )
+
+
+def save_identity(profile: IdentityProfile) -> bool:
+    """Persist the profile atomically; False when the disk refuses."""
+    path = identity_path()
+    payload = {
+        "identity": profile.identity,
+        "tone": profile.tone,
+        "behavior_rules": profile.behavior_rules,
+        "interaction_style": profile.interaction_style,
+        "updated_at": time.strftime("%Y-%m-%dT%H:%M:%S"),
+    }
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = path.with_suffix(".json.tmp")
+        tmp.write_text(json.dumps(payload, indent=2, ensure_ascii=False), encoding="utf-8")
+        tmp.replace(path)
+        return True
+    except OSError:
+        return False
+
+
+__all__ = ["IdentityProfile", "identity_path", "load_identity", "save_identity"]

seedcode/core/lifecycle.py

@@ -0,0 +1,240 @@
+"""Agent lifecycle: a single, explicit state machine for the whole app.
+
+The auto-exit bug was architectural, not cosmetic: nothing in the codebase
+distinguished "a task finished" from "the application should terminate", so
+termination could be triggered from deep inside a tool run (a window-close
+that hit our own terminal, an unhandled exception escaping a turn, a cleanup
+path that escalated). This module makes that structurally impossible:
+
+* The REPL is always the owner of process lifetime. A turn is a *function
+  call* into the engine; whatever the turn does — succeed, fail, crash, get
+  cancelled — control returns to the prompt. Nothing below the REPL may end
+  the process.
+* Shutdown is a *decision*, made in exactly one place: :func:`request_exit`,
+  called only when the user explicitly asks to quit (the /exit command, the
+  menu's Exit item, or Ctrl+D). No tool, task outcome, or error path can
+  reach it.
+* The state machine records where the app is (IDLE → PLANNING → EXECUTING →
+  VERIFYING → RESPONDING → IDLE) and enforces that the only legal transition
+  out of the task cycle is back to IDLE. Entering SHUTDOWN is validated:
+  it is legal *only* from IDLE, and only when an exit was explicitly
+  requested. A stray attempt (a bug somewhere deep calling shutdown after a
+  task) raises :class:`LifecycleError` loudly instead of silently dying.
+
+Keep this module dependency-free: everything in the app should be able to
+import it.
+"""
+
+from __future__ import annotations
+
+import enum
+import threading
+from typing import Callable
+
+
+class LifecycleError(RuntimeError):
+    """An illegal lifecycle transition was attempted (a real bug somewhere)."""
+
+
+@enum.unique
+class Phase(str, enum.Enum):
+    """Where the application currently is in the task cycle."""
+
+    IDLE = "idle"                # at the prompt, waiting for the user
+    PLANNING = "planning"        # a turn started; the model is thinking
+    EXECUTING = "executing"      # tools / desktop actions are running
+    VERIFYING = "verifying"      # outcomes are being checked
+    RESPONDING = "responding"    # the final answer is being produced
+    SHUTDOWN = "shutdown"        # the app is exiting (terminal state)
+
+
+# Legal transitions. The task cycle is a strict forward chain that must end
+# back at IDLE; IDLE may also go straight to SHUTDOWN (explicit exit).
+_ALLOWED: dict[Phase, frozenset[Phase]] = {
+    Phase.IDLE: frozenset({Phase.PLANNING, Phase.SHUTDOWN}),
+    Phase.PLANNING: frozenset({Phase.EXECUTING, Phase.IDLE}),
+    Phase.EXECUTING: frozenset({Phase.VERIFYING, Phase.IDLE}),
+    Phase.VERIFYING: frozenset({Phase.RESPONDING, Phase.IDLE}),
+    Phase.RESPONDING: frozenset({Phase.IDLE}),  # NEVER SHUTDOWN from here
+    # SHUTDOWN is terminal: no transitions out (validated implicitly because
+    # nothing lists SHUTDOWN as a source).
+    Phase.SHUTDOWN: frozenset(),
+}
+
+# Phases a user turn passes through, in order.
+_TASK_PATH = (Phase.PLANNING, Phase.EXECUTING, Phase.VERIFYING, Phase.RESPONDING)
+
+
+class Lifecycle:
+    """The app-wide lifecycle state machine (one instance per process).
+
+    The REPL advances it around each user turn; the exit decision is the only
+    path to SHUTDOWN. Thread-safe because desktop work can run on helper
+    threads.
+    """
+
+    def __init__(self) -> None:
+        self._phase = Phase.IDLE
+        # Set only by :meth:`request_exit` — the explicit user decision.
+        self._exit_requested = False
+        self._lock = threading.RLock()
+        self._on_shutdown: list[Callable[[], None]] = []
+
+    # --- introspection -------------------------------------------------------
+    @property
+    def phase(self) -> Phase:
+        with self._lock:
+            return self._phase
+
+    @property
+    def exit_requested(self) -> bool:
+        """Whether the user has explicitly asked to quit."""
+        with self._lock:
+            return self._exit_requested
+
+    def is_running(self) -> bool:
+        """Whether the app should keep running (the REPL's loop condition)."""
+        with self._lock:
+            return not self._exit_requested and self._phase is not Phase.SHUTDOWN
+
+    # --- turn transitions ----------------------------------------------------
+    def begin_turn(self) -> None:
+        """IDLE → PLANNING. A user turn starts (raises unless at IDLE)."""
+        with self._lock:
+            self._transition(Phase.PLANNING)
+
+    def to_executing(self) -> None:
+        with self._lock:
+            self._transition(Phase.EXECUTING)
+
+    def to_verifying(self) -> None:
+        with self._lock:
+            self._transition(Phase.VERIFYING)
+
+    def to_responding(self) -> None:
+        with self._lock:
+            self._transition(Phase.RESPONDING)
+
+    def end_turn(self) -> None:
+        """Whatever phase the turn reached → IDLE. Always call in ``finally``.
+
+        Every path out of a turn — success, tool failure, provider error,
+        cancellation, even a crash inside the engine — funnels here, which is
+        precisely the guarantee the auto-exit bug violated.
+        """
+        with self._lock:
+            if self._phase is Phase.IDLE:
+                return  # a nested/sub-turn already closed out
+            self._transition(Phase.IDLE)
+
+    # --- the one exit path ---------------------------------------------------
+    def request_exit(self, reason: str = "") -> None:
+        """Record the user's explicit decision to quit.
+
+        Only interactive, unambiguous user actions may call this: the /exit
+        command, the menu's Exit item, or Ctrl+D at the prompt. A task's
+        completion — however it ends — must never reach this method.
+        """
+        with self._lock:
+            self._exit_requested = True
+            if reason:
+                import logging
+
+                logging.getLogger("seedcode.lifecycle").info(
+                    "exit requested: %s", reason
+                )
+
+    def shutdown(self) -> None:
+        """Enter SHUTDOWN and run registered teardown hooks.
+
+        Validates the transition: legal only from IDLE with an explicit exit
+        request. A cleanup path or tool that tries to shut the app down after
+        (or during) a task fails loudly instead of killing the process.
+        """
+        with self._lock:
+            if self._phase is Phase.SHUTDOWN:
+                return
+            if self._phase is not Phase.IDLE:
+                raise LifecycleError(
+                    f"shutdown attempted from {self._phase.value} — a task is "
+                    "still running. Shutdown is only legal from IDLE after an "
+                    "explicit exit request."
+                )
+            if not self._exit_requested:
+                raise LifecycleError(
+                    "shutdown attempted without an explicit exit request — "
+                    "normal task completion must never terminate the app."
+                )
+            self._transition(Phase.SHUTDOWN)
+            hooks = list(self._on_shutdown)
+        for hook in hooks:
+            try:
+                hook()
+            except Exception:
+                pass  # teardown is best-effort by contract
+
+    def on_shutdown(self, hook: Callable[[], None]) -> None:
+        """Register a best-effort teardown hook (flush logs, save state...)."""
+        with self._lock:
+            self._on_shutdown.append(hook)
+
+    def task_span(self) -> "_TaskSpan":
+        """Context manager for one full user turn: begin → … → end, always.
+
+        Usage in the REPL::
+
+            with lifecycle().task_span():
+                run_the_whole_turn()
+
+        Whatever the turn does — succeed, fail, raise, get cancelled — the
+        ``finally`` returns the machine to IDLE so the REPL prompts again.
+        """
+        return _TaskSpan(self)
+
+    # --- internals -----------------------------------------------------------
+    def _transition(self, target: Phase) -> None:
+        if target not in _ALLOWED[self._phase]:
+            raise LifecycleError(
+                f"Illegal lifecycle transition {self._phase.value} -> "
+                f"{target.value}. Legal: "
+                f"{', '.join(p.value for p in _ALLOWED[self._phase])}."
+            )
+        self._phase = target
+
+    def reset_for_tests(self) -> None:
+        """Back to IDLE with no exit request (test isolation only)."""
+        with self._lock:
+            self._phase = Phase.IDLE
+            self._exit_requested = False
+            self._on_shutdown.clear()
+
+
+# The process-wide lifecycle. The REPL owns it; everything else may read it.
+_lifecycle = Lifecycle()
+
+
+def lifecycle() -> Lifecycle:
+    """The process-wide :class:`Lifecycle` instance."""
+    return _lifecycle
+
+
+class _TaskSpan:
+    """One full user turn on a :class:`Lifecycle` (see :meth:`Lifecycle.task_span`)."""
+
+    def __init__(self, lc: Lifecycle) -> None:
+        self._lc = lc
+
+    def __enter__(self) -> "_TaskSpan":
+        self._lc.begin_turn()
+        return self
+
+    def __exit__(self, exc_type, exc, tb) -> bool:
+        # Swallow nothing: the exception (if any) propagates to the REPL's
+        # own handler; the lifecycle just guarantees the return to IDLE.
+        self._lc.end_turn()
+        return False
+
+
+def task_span() -> "_TaskSpan":
+    """One full user turn on the process-wide lifecycle."""
+    return _lifecycle.task_span()

seedcode/core/limits.py

@@ -0,0 +1,35 @@
+"""Central retry/step limits for the operator stack.
+
+One module owns every bound so a confused loop can never spin forever and
+the numbers are tunable in one place:
+
+* ``MAX_ACTION_RETRIES``     — one action re-tried after failure
+* ``MAX_RECOVERY_ATTEMPTS``  — recovery-strategy applications per failure
+* ``MAX_STALE_REQUERY``      — stale-element re-query cycles per action
+* ``MAX_PLAN_STEPS``         — planner steps per goal (the agent loop has its
+  own unrelated ``MAX_STEPS`` for tool calls; this bounds plan expansion)
+* ``MAX_TASK_DURATION_S``    — wall-clock ceiling for one orchestrated task
+* ``MAX_WAIT_FOR_*``         — state-based wait ceilings (no blind sleeps)
+
+All values are plain ints/floats; a config layer may clamp them downward but
+the defaults are the safety floor.
+"""
+
+from __future__ import annotations
+
+MAX_ACTION_RETRIES = 2
+MAX_RECOVERY_ATTEMPTS = 2
+MAX_STALE_REQUERY = 2
+MAX_PLAN_STEPS = 12
+MAX_TASK_DURATION_S = 300.0
+
+# State-based waits (used instead of blind sleeps everywhere).
+MAX_WAIT_WINDOW_S = 10.0     # a window/app to appear
+MAX_WAIT_ELEMENT_S = 8.0     # a UI/DOM element to appear
+MAX_WAIT_NAVIGATION_S = 15.0  # a page navigation to settle
+MAX_WAIT_POLL_S = 0.25       # poll cadence for state waits
+
+
+def clamp_wait(seconds: float, ceiling: float) -> float:
+    """Clamp a wait to [0, ceiling]; negative becomes 0."""
+    return max(0.0, min(float(seconds), ceiling))