fix: address Scroll pre-commit checks

Author: niceIrene

README.md

@@ -45,16 +45,12 @@ serving, rate limits, and stochastic generation can affect reruns.
 
 ## Evaluation and reproduction
 
-Evaluation is conducted with
-[AgentZero](https://github.com/agentscope-ai/AgentZero), our open-source
-Harbor-based evaluation framework, so benchmark-specific adapters, task
-definitions, verifiers, and generated runs remain separate from the Scroll
-implementation.
-
-AgentZero pins this repository as a Git submodule and records the exact QwenPaw
-commit used by an evaluation. It provides the Harbor workflows for
-LongMemEval, BEAM, RULER, and LOCA, including environment construction,
-parallel trials, traces, and scoring.
+Implementations for reproducing the reported results are available in
+[AgentZero](https://github.com/agentscope-ai/AgentZero). AgentZero uses Harbor
+and pins this repository as a Git submodule, recording the exact QwenPaw commit
+used by each evaluation. It provides reproduction workflows for LongMemEval,
+BEAM, RULER, and LOCA, including environment construction, parallel trials,
+traces, and scoring.
 
 ```bash
 git clone --recurse-submodules https://github.com/agentscope-ai/AgentZero.git
@@ -66,42 +62,48 @@ source .venv/bin/activate
 uv pip install "harbor==0.18.0" "ijson>=3.3.0"
 ```
 
-Build the pinned Scroll/QwenPaw wheel, then generate a small LongMemEval task
-set:
+Build the pinned Scroll/QwenPaw wheel:
 
 ```bash
 uv build --project qwenpaw --wheel --out-dir dist
 export QWENPAW_WHEEL="$(find "$PWD/dist" -name 'qwenpaw-*.whl' -print -quit)"
 export PYTHONPATH="$PWD${PYTHONPATH:+:$PYTHONPATH}"
-
-python scripts/download_longmemeval_data.py --dataset oracle
-python benchmarks/longmemeval/generate.py \
-  benchmarks/longmemeval/data/longmemeval_oracle.json \
-  --split smoke \
-  --output local-tasks/longmemeval \
-  --limit 3
 ```
 
-Supply your own evaluated-model and judge API keys, base URLs, and model
-identifiers, then launch Harbor:
+Choose a benchmark (`longmemeval`, `beam`, `ruler`, or `loca`) and prepare its
+task packages using the corresponding AgentZero instructions. Then select its
+task path and adapter:
+
+| Benchmark | Task path | Adapter |
+| --- | --- | --- |
+| LongMemEval | `local-tasks/longmemeval/{split}` | `adapters.qwenpaw.longmemeval:QwenPawLongMemEvalAgent` |
+| BEAM | `local-tasks/beam/{task}` | `adapters.qwenpaw.beam:QwenPawBeamAgent` |
+| RULER | `local-tasks/ruler` | `adapters.qwenpaw.ruler:QwenPawRulerAgent` |
+| LOCA | `local-tasks/loca/{task}` | `adapters.qwenpaw.loca:QwenPawLOCAAgent` |
+
+Supply your own model API key, base URL, and model identifier, replace the
+placeholders below, and launch Harbor:
 
 ```bash
+export BENCHMARK=YOUR_BENCHMARK
+export TASK_PATH=YOUR_TASK_PATH
+export ADAPTER=YOUR_ADAPTER
+
 harbor run \
-  --job-name longmemeval-scroll-smoke \
-  -p local-tasks/longmemeval/smoke \
-  -a adapters.qwenpaw.longmemeval:QwenPawLongMemEvalAgent \
+  --job-name "scroll-${BENCHMARK}" \
+  -p "$TASK_PATH" \
+  -a "$ADAPTER" \
   -m YOUR_PROVIDER_ID/YOUR_MODEL_ID \
   --ae QWENPAW_WHEEL="$QWENPAW_WHEEL" \
   --ae QWENPAW_MODEL_API_KEY="$QWENPAW_MODEL_API_KEY" \
   --ae QWENPAW_MODEL_BASE_URL="$QWENPAW_MODEL_BASE_URL" \
-  --ve LONGMEMEVAL_JUDGE_API_KEY="$LONGMEMEVAL_JUDGE_API_KEY" \
-  --ve LONGMEMEVAL_JUDGE_BASE_URL="$LONGMEMEVAL_JUDGE_BASE_URL" \
-  --ve LONGMEMEVAL_JUDGE_MODEL="$LONGMEMEVAL_JUDGE_MODEL" \
-  -n 3
+  -n 8
 ```
 
-See the AgentZero README for Oracle validation, full S/M runs, other
-benchmarks, concurrency guidance, and result inspection.
+For judged benchmarks, also pass the benchmark-specific judge API key, base
+URL, and model identifier documented in AgentZero. See the AgentZero README
+for task generation, Oracle validation, concurrency guidance, and result
+inspection.
 
 ## License
 

src/qwenpaw/agents/context/scroll/repl.py

@@ -20,7 +20,6 @@
 import sys
 import uuid
 from pathlib import Path
-from types import SimpleNamespace
 from typing import Any, Optional
 
 from agentscope.message import TextBlock, ToolResultState
@@ -207,25 +206,31 @@ async def _run_kernel(source: str) -> tuple[str, bool] | None:
         except KernelUnavailableError:
             return None
 
-        async def _blocked_dispatch(
-            exposed_path: str,
-            _args: dict[str, Any],
-            *,
-            kernel_task_id: str,
-        ) -> Any:
-            raise ToolForwardingError(
-                f"failed|paw.tools.{exposed_path} is not available inside "
-                "recall_history_python cells; query via ms directly, or use "
-                "repl_exec for governed tool calls",
-            )
-
         # Shim bridge: carrying the handle's current specs makes the manager's
         # spec refresh a no-op, and recall cells stay pure Python + ms.
-        bridge = SimpleNamespace(
-            specs=handle.specs,
-            is_read_only=lambda _path: False,
-            dispatch=_blocked_dispatch,
-        )
+        class _BlockedBridge:
+            def __init__(self) -> None:
+                self.specs = handle.specs
+
+            @staticmethod
+            def is_read_only(_exposed_path: str) -> bool:
+                return False
+
+            @staticmethod
+            async def dispatch(
+                exposed_path: str,
+                _args: dict[str, Any],
+                *,
+                kernel_task_id: str,
+            ) -> Any:
+                del kernel_task_id
+                raise ToolForwardingError(
+                    f"failed|paw.tools.{exposed_path} is not available inside "
+                    "recall_history_python cells; query via ms directly, or "
+                    "use repl_exec for governed tool calls",
+                )
+
+        bridge = _BlockedBridge()
         try:
             result = await manager.execute(
                 handle,

src/qwenpaw/repl/errors.py

@@ -73,9 +73,14 @@
     "auth_missing": (
         "Credentials are missing. Ask the user to authenticate; do not retry."
     ),
-    "rate_limited": "Wait or reduce call frequency, then retry a limited number of times.",
+    "rate_limited": (
+        "Wait or reduce call frequency, then retry a limited number of times."
+    ),
     "timeout": "The call timed out. Reduce the workload or retry once.",
-    "interrupted": "The cell was interrupted. Variables are retained; retry if appropriate.",
+    "interrupted": (
+        "The cell was interrupted. Variables are retained; retry if "
+        "appropriate."
+    ),
     "kernel_restarted": (
         "The kernel restarted and variables were lost. Re-run the required "
         "setup cells or restore persisted variables."
@@ -114,10 +119,10 @@ def make_error(
     }
 
 
-def classify_exception(exc: BaseException) -> dict[str, Any]:
+def classify_exception(  # pylint: disable=too-many-return-statements
+    exc: BaseException,
+) -> dict[str, Any]:
     """Map a Python exception raised inside a cell to a structured error."""
-    import ast  # noqa: F401  (kept local to avoid import-time cost)
-
     from .proxy_runtime import PawToolError
 
     if isinstance(exc, PawToolError):

src/qwenpaw/repl/exec_server.py

@@ -287,7 +287,10 @@ def _execute_tree(
     if prefix.body:
         exec(compile(prefix, "<cell>", "exec"), namespace)  # noqa: S102
     expression = ast.Expression(tree.body[-1].value)
-    value = eval(compile(expression, "<cell>", "eval"), namespace)  # noqa: S307
+    value = eval(
+        compile(expression, "<cell>", "eval"),
+        namespace,
+    )  # noqa: S307
     if value is not None:
         rendered = render_last_expression(value, display)
         if rendered is not None:
@@ -402,6 +405,7 @@ def __init__(self, exec_id: str) -> None:
         self.interrupt_injected = False
 
 
+# pylint: disable-next=too-many-branches,too-many-statements
 def _serve_message_loop(
     inbox: queue.Queue,
     channel: StdioKernelChannel,

src/qwenpaw/repl/governance_bridge.py

@@ -14,15 +14,15 @@
 import json
 import mimetypes
 import uuid
-from collections.abc import Iterator, Mapping
+from collections.abc import Iterator, Mapping, Sequence
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
 from .proxy_runtime import sanitize_name
 
 EXCLUDED_TOOLS = frozenset(
-    {"repl_exec", "execute_python", "execute_python_code"}
+    {"repl_exec", "execute_python", "execute_python_code"},
 )
 
 
@@ -35,9 +35,9 @@ class CodeProvenance:
     provenance: str = "code"
 
 
-_CURRENT_PROVENANCE: contextvars.ContextVar[CodeProvenance | None] = (
-    contextvars.ContextVar("qwenpaw_repl_provenance", default=None)
-)
+_CURRENT_PROVENANCE: contextvars.ContextVar[
+    CodeProvenance | None
+] = contextvars.ContextVar("qwenpaw_repl_provenance", default=None)
 
 
 def get_code_provenance() -> CodeProvenance | None:
@@ -94,7 +94,7 @@ def _mcp_path(tool: Any, fallback_name: str) -> str | None:
     if capability is not None and getattr(capability, "protocol", "") == "mcp":
         server = sanitize_name(str(getattr(capability, "driver_name", "mcp")))
         original = sanitize_name(
-            str(getattr(capability, "name", fallback_name))
+            str(getattr(capability, "name", fallback_name)),
         )
         return f"mcp.{server}.{original}"
     if bool(getattr(tool, "is_mcp", False)):
@@ -182,7 +182,7 @@ def __init__(
         agent_state: Any,
         workspace: Path,
         workspace_id: str,
-        specs: list[Mapping[str, Any]],
+        specs: Sequence[Mapping[str, Any]],
     ) -> None:
         self.toolkit = toolkit
         self.agent_state = agent_state
@@ -263,24 +263,27 @@ def _resolve_tool(self, exposed_path: str) -> str:
         return name
 
     def _save_media(
-        self, block: Any, call_id: str, position: int
+        self,
+        block: Any,
+        call_id: str,
+        position: int,
     ) -> dict[str, str]:
         source = _block_attr(block, "source")
         media_type = str(
-            _block_attr(source, "media_type", "application/octet-stream")
+            _block_attr(source, "media_type", "application/octet-stream"),
         )
         data = _block_attr(source, "data")
         if not isinstance(data, str):
             raise ToolForwardingError(
-                "binary tool result did not contain base64 data"
+                "binary tool result did not contain base64 data",
             )
         relative = Path("out") / (
             f"tool_{call_id}_{position}{_media_extension(media_type)}"
         )
         destination = (self.workspace / relative).resolve()
         if self.workspace not in destination.parents:
             raise ToolForwardingError(
-                "media result path escaped the workspace"
+                "media result path escaped the workspace",
             )
         destination.parent.mkdir(parents=True, exist_ok=True)
         destination.write_bytes(base64.b64decode(data, validate=True))

src/qwenpaw/repl/kernel_manager.py

@@ -18,12 +18,12 @@
 import uuid
 from dataclasses import dataclass, field
 from pathlib import Path
-from typing import Any
+from typing import Any, Protocol
 
 from ..sandbox import MountSpec, SandboxConfig, SandboxMode
 from .backend import resolve_backend_kind
 from .errors import classify_tool_error, make_error
-from .governance_bridge import GovernanceBridge, ToolForwardingError
+from .governance_bridge import ToolForwardingError
 from .output_policy import DEFAULT_STDOUT_LIMIT
 from .persistence import latest_snapshot_dir
 from .protocol import (
@@ -45,6 +45,24 @@
 RESTORE_ACK_TIMEOUT = 15.0
 
 
+class KernelToolBridge(Protocol):
+    """Tool-forwarding interface required while servicing a kernel cell."""
+
+    specs: list[dict[str, Any]]
+
+    def is_read_only(self, exposed_path: str) -> bool:
+        """Return whether a tool may be forwarded concurrently."""
+
+    async def dispatch(
+        self,
+        exposed_path: str,
+        args: dict[str, Any],
+        *,
+        kernel_task_id: str,
+    ) -> Any:
+        """Forward a governed tool call."""
+
+
 class KernelUnavailableError(RuntimeError):
     """The REPL cannot safely start on this platform or configuration."""
 
@@ -387,7 +405,7 @@ def _bwrap_supports_clearenv(executable: str) -> bool:
     return _CLEARENV_SUPPORTED
 
 
-def _bubblewrap_command(
+def _bubblewrap_command(  # pylint: disable=too-many-branches
     config: SandboxConfig,
     argv: list[str],
 ) -> list[str]:
@@ -468,13 +486,12 @@ def _seatbelt_command(
     from ..sandbox.macos_sandbox import MacOSSandbox
 
     sandbox = MacOSSandbox(config)
-    profile = (
-        sandbox._compile_seatbelt_profile()
-    )  # pylint: disable=protected-access
+    # pylint: disable-next=protected-access
+    profile = sandbox._compile_seatbelt_profile()
     executable = shutil.which("sandbox-exec")
     if executable is None:
         raise KernelUnavailableError(
-            "sandbox-exec disappeared after capability probe"
+            "sandbox-exec disappeared after capability probe",
         )
     return [executable, "-p", profile, *argv]
 
@@ -771,7 +788,9 @@ async def _maybe_restore_snapshot(
             )
 
     async def _send(
-        self, handle: KernelHandle, message: dict[str, Any]
+        self,
+        handle: KernelHandle,
+        message: dict[str, Any],
     ) -> None:
         if (
             handle.process.stdin is None
@@ -828,11 +847,11 @@ async def _update_specs(
         handle.specs = stable_specs
         handle.specs_hash = new_hash
 
-    async def execute(
+    async def execute(  # pylint: disable=too-many-branches,too-many-statements
         self,
         handle: KernelHandle,
         code: str,
-        bridge: GovernanceBridge,
+        bridge: KernelToolBridge,
         *,
         timeout: float = DEFAULT_EXEC_TIMEOUT,
         display: str = "summary",
@@ -1043,7 +1062,7 @@ async def respond_interrupted(
                             exec_id=exec_id,
                             ok=result.ok,
                             error_kind=(
-                                result.error.get("kind")
+                                str(result.error.get("kind") or "")
                                 if result.error
                                 else ""
                             ),
@@ -1154,7 +1173,7 @@ async def _drain_background_cell(
                     if handle.process.returncode is not None:
                         raise KernelCrashedError(
                             self._crash_message(handle),
-                        )
+                        ) from None
                     continue
                 message_type = message["type"]
                 if message_type == "log":