vis-agent 0.2.32.dev7313__tar.gz → 0.2.32.dev7344__tar.gz

{vis_agent-0.2.32.dev7313 → vis_agent-0.2.32.dev7344}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vis-agent
-Version: 0.2.32.dev7313
+Version: 0.2.32.dev7344
 Summary: The Vis Python SDK — author extensions and control local or remote engines.
 Project-URL: Homepage, https://vis.blockether.com
 Project-URL: Documentation, https://vis.blockether.com

{vis_agent-0.2.32.dev7313 → vis_agent-0.2.32.dev7344}/pyproject.toml

@@ -8,7 +8,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vis-agent"
-version = "0.2.32.dev7313"
+version = "0.2.32.dev7344"
 description = "The Vis Python SDK — author extensions and control local or remote engines."
 readme = "README.md"
 requires-python = ">=3.11"

{vis_agent-0.2.32.dev7313 → vis_agent-0.2.32.dev7344}/src/blockether/vis/_outside.py

@@ -21,11 +21,15 @@ import uuid
 from copy import deepcopy
 from datetime import date
 from pathlib import Path
+from typing import TYPE_CHECKING, Any
 
 from blockether.vis import _contracts
 
+if TYPE_CHECKING:
+    from blockether.vis.extension import Host
 
-def check_host(host):
+
+def check_host(host) -> Host:
     """Refuse a host that does not answer every implemented host operation.
 
     Returns the host, so a constructor can `return check_host(built)`. An incomplete
@@ -412,7 +416,7 @@ class _Run:
 def _result(run, stage, **extra):
     code = run.poll()
     now = time.time()
-    result = dict.fromkeys(_SHELL_RESULT_KEYS)
+    result: dict[str, Any] = dict.fromkeys(_SHELL_RESULT_KEYS)
     out, next_offset, omitted = run.read(
         extra.pop("_offset", None), extra.pop("_limit", None)
     )
@@ -1083,6 +1087,7 @@ def _live_apply(view, op):
         complaint = _live_check_node(spec, _live_ids(view["nodes"]))
         if complaint:
             raise Refused(complaint)
+        assert isinstance(spec, dict)  # _live_check_node refuses any other spec.
         found = _live_find(view["nodes"], op.get("after"))
         # A new node joins the row that holds the node it named, not the top of
         # the view: `after` is a sibling, so the arrangement stays the one declared.
@@ -1234,6 +1239,7 @@ def live(envelope_json):
         complaint = _check_view(view)
         if complaint:
             raise Refused(complaint)
+        assert isinstance(view, dict)  # _check_view refuses any other view.
         view_id = str(uuid.uuid4())
         held = {"view_id": view_id, "view": json.loads(json.dumps(view)), "seq": 0}
         held["condition"] = threading.Condition()

{vis_agent-0.2.32.dev7313 → vis_agent-0.2.32.dev7344}/src/blockether/vis/engine/_agent.py

@@ -11,7 +11,7 @@ from typing import Any, TypeVar, overload
 from jsonschema import Draft202012Validator, validators
 from jsonschema.exceptions import ValidationError, best_match
 from pydantic import BaseModel
-from pydantic_core import SchemaError, SchemaValidator, core_schema
+from pydantic_core import ErrorDetails, SchemaError, SchemaValidator, core_schema
 from pydantic_core import ValidationError as PydanticValidationError
 from referencing import Registry
 from referencing.exceptions import Unresolvable
@@ -173,7 +173,7 @@ def _schema_problems(error: ValidationError, show_input: bool):
     """Describe a JSON Schema error without printing whole objects or arrays."""
     path = tuple(error.absolute_path)
     keyword, expected, value = error.validator, error.validator_value, error.instance
-    if keyword == "required" and isinstance(value, dict):
+    if keyword == "required" and isinstance(value, dict) and isinstance(expected, list):
         for name in expected:
             if name not in value:
                 yield _problem("schema", (*path, name), "required property is missing")
@@ -352,7 +352,7 @@ class _ResponseContract:
             for item in details
         )
 
-    def _pydantic_message(self, item: dict) -> str:
+    def _pydantic_message(self, item: ErrorDetails) -> str:
         value = item.get("input")
         if self.show_input and item["type"] != "missing" and _is_scalar(value):
             return f"{item['msg']} (input: {_brief(value)})"
@@ -426,7 +426,7 @@ class Agent:
                 self._session = self.execution_layer.create_session(
                     **self._session_options
                 )
-                self._mount_extensions(self._extensions)
+                self._mount_extensions(self._session, self._extensions)
             except BaseException:
                 try:
                     self.close()
@@ -435,13 +435,13 @@ class Agent:
                 raise
         return self._session
 
-    def _mount_extensions(self, extensions):
+    def _mount_extensions(self, session: Session, extensions):
         if extensions.manifest:
             self.execution_layer._ensure_client_lease()
             self.execution_layer.put_session_client_extensions(
-                self._session.id, body={"extensions": extensions.manifest}
+                session.id, body={"extensions": extensions.manifest}
             )
-        self.execution_layer._client_extensions[self._session.id] = extensions
+        self.execution_layer._client_extensions[session.id] = extensions
 
     def register_extension(self, extension):
         """Add an application-owned Extension before this Agent's first request.
@@ -458,7 +458,7 @@ class Agent:
             raise RuntimeError("register extensions before the Agent's first request")
         candidate = ClientExtensions((*self._extensions.declarations, extension))
         if self._session is not None:
-            self._mount_extensions(candidate)
+            self._mount_extensions(self._session, candidate)
         self._extensions = candidate
 
     def send(self, request: str, **options) -> Turn:

{vis_agent-0.2.32.dev7313 → vis_agent-0.2.32.dev7344}/src/blockether/vis/engine/_client.py

@@ -7,6 +7,7 @@ means that a submitted mutation was rolled back.
 
 from __future__ import annotations
 
+import inspect
 import json
 import math
 import threading
@@ -135,7 +136,7 @@ def _field(data: Any, name: str, kind: type) -> Any:
     value = data.get(name) if isinstance(data, dict) else None
     if type(value) is not kind or (kind is str and not value):
         raise ProtocolError(f"invalid response field: {name}")
-    if kind is int and value < 0:
+    if type(value) is int and value < 0:
         raise ProtocolError(f"invalid response field: {name}")
     return value
 
@@ -286,7 +287,7 @@ class ExecutionLayer(ABC):
     @abstractmethod
     def _open(
         self, method, route, *, query=None, body=None, content=None, timeout=None
-    ):
+    ) -> Any:
         """Run one transport exchange. Do not retry mutations."""
 
     def _ensure_client_lease(self, *, pid: int | None = None) -> str:
@@ -297,7 +298,8 @@ class ExecutionLayer(ABC):
             if pid is not None:
                 body["pid"] = pid
             lease = self._request("POST", "/v1/clients", body=body).json()
-            self._lease = _field(lease, "client_id", str)
+            client_id: str = _field(lease, "client_id", str)
+            self._lease = client_id
         return self._lease
 
     def __enter__(self):
@@ -364,7 +366,8 @@ class ExecutionLayer(ABC):
                     f"maximum is {_MAX_DECISION_ARCHIVE} bytes"
                 )
         names = {s[1:] for s in route.split("/") if s.startswith(":")}
-        if set(path or {}) != names:
+        path = path or {}
+        if set(path) != names:
             raise ValueError("path parameters do not match route")
         resolved = "/".join(
             _segment(path[s[1:]]) if s.startswith(":") else s for s in route.split("/")
@@ -2995,6 +2998,9 @@ class GatewayClient(ExecutionLayer):
         if upload_sha256 is not None:
             headers["Content-Type"] = "application/zip"
             headers["Transfer-Encoding"] = "chunked"
+            # _request sends a hash only with a bounded stream and its length.
+            assert content is not None and not isinstance(content, bytes)
+            assert upload_length is not None
             content = _UploadStream(content, upload_length)
             headers["X-Content-SHA256"] = upload_sha256
         url = self._url + route + ("?" + urlencode(query) if query else "")
@@ -3136,7 +3142,7 @@ class Session:
     client: ExecutionLayer
     id: str
 
-    def _call(self, method, suffix="", **kwargs):
+    def _call(self, method, suffix="", **kwargs) -> Any:
         path = {"sid": self.id, **kwargs.pop("path", {})}
         response = self.client._request(
             method, "/v1/sessions/:sid" + suffix, path=path, **kwargs
@@ -3476,7 +3482,7 @@ class _EventStream:
         if self._raw is not None:
             self._raw.close()
         # A pipe failure can close its owning client from inside this generator.
-        if not self._iterator.gi_running:
+        if inspect.getgeneratorstate(self._iterator) != inspect.GEN_RUNNING:
             self._iterator.close()
         self.client._streams.discard(self)
 
@@ -3533,8 +3539,16 @@ class _EventStream:
     def _terminal(self, event):
         return False
 
+    def _endpoint(self):
+        """Return the route and query of this subscription."""
+        raise NotImplementedError
+
+    def _accept(self, name, value):
+        """Return the event of one frame, or None to skip the frame."""
+        raise NotImplementedError
 
-class _PollingEvents:
+
+class _PollingEvents(_EventStream):
     """Poll finite event pages so callback code runs on the SDK calling thread."""
 
     def _iterate(self):
@@ -3558,6 +3572,10 @@ class _PollingEvents:
     def _pump(self):
         pass
 
+    def _page(self):
+        """Return the next finite page of `(event name, value)` pairs."""
+        raise NotImplementedError
+
 
 class Events(_EventStream):
     """Iterate typed session events, with replay and bounded reconnection.
@@ -3604,6 +3622,7 @@ class Events(_EventStream):
         if name is not None and name != event.type:
             raise ProtocolError("event name disagrees with payload")
         seq = event.cursor if event.type == "subscription.ready" else event.seq
+        assert seq is not None  # Event.from_wire requires the field of each type.
         if event.type == "subscription.ready" or seq > self.cursor:
             self.cursor = seq
             return event

{vis_agent-0.2.32.dev7313 → vis_agent-0.2.32.dev7344}/src/blockether/vis/engine/_local.py

@@ -117,11 +117,13 @@ class LocalEngine(ExecutionLayer):
             raise NotADirectoryError(str(path))
         return {"root": str(path)}
 
-    def _ensure_client_lease(self) -> str:
+    def _ensure_client_lease(self, *, pid: int | None = None) -> str:
         # Stdio shares the application host; its PID keeps idle callbacks alive.
-        return super()._ensure_client_lease(pid=os.getpid())
+        return super()._ensure_client_lease(pid=os.getpid() if pid is None else pid)
 
     def _read_line(self, deadline):
+        # connect() starts the engine with piped stdio before any read.
+        assert self._process is not None and self._process.stdout is not None
         while b"\n" not in self._buffer:
             remaining = deadline - time.monotonic()
             if (
@@ -176,6 +178,7 @@ class LocalEngine(ExecutionLayer):
                     stderr=stderr,
                     start_new_session=True,
                 )
+            assert self._process.stdin is not None  # Popen got stdin=PIPE.
             os.set_blocking(self._process.stdin.fileno(), False)
             hello = self._read_line(time.monotonic() + self._startup_timeout)
             if (
@@ -197,6 +200,7 @@ class LocalEngine(ExecutionLayer):
         self, method, route, *, query=None, body=None, content=None, timeout=None
     ):
         self.connect()
+        assert self._process is not None and self._process.stdin is not None
         deadline = time.monotonic() + _duration(
             self.timeout if timeout is None else timeout
         )
@@ -296,14 +300,14 @@ class LocalEngine(ExecutionLayer):
             if process.stdout:
                 process.stdout.close()
         if self._home is not None:
-            self._stderr_tail = self._stderr_end()
+            self._stderr_tail = self._stderr_end(self._home.name)
             self._home.cleanup()
         self._cleanup_complete = True
 
-    def _stderr_end(self):
-        """Return the end of the engine's stderr log, from a line start."""
+    def _stderr_end(self, home):
+        """Return the end of the engine's stderr log in `home`, from a line start."""
         try:
-            with open(Path(self._home.name) / "stderr.log", "rb") as stream:
+            with open(Path(home) / "stderr.log", "rb") as stream:
                 size = stream.seek(0, os.SEEK_END)
                 stream.seek(max(0, size - _STDERR_TAIL))
                 end = stream.read()

{vis_agent-0.2.32.dev7313 → vis_agent-0.2.32.dev7344}/src/blockether/vis/extension.py

@@ -27,6 +27,7 @@ from typing import (
     Annotated,
     Any,
     ClassVar,
+    Generic,
     Literal,
     Optional,
     Protocol,
@@ -39,6 +40,9 @@ from typing import (
     runtime_checkable,
 )
 
+# A setting value: `bool` for a boolean setting, `str` for a choice setting.
+_SettingValue = TypeVar("_SettingValue", bool, str)
+
 
 @runtime_checkable
 class Host(Protocol):
@@ -46,47 +50,60 @@ class Host(Protocol):
 
     def workspace_root(self) -> str:
         """Read the active session working copy, or the outside process directory."""
+        ...
 
     def setting_declaration(self, spec: Mapping[str, Any]) -> Mapping[str, Any]:
         """Validate a declaration and fill defaults from the contract schema."""
+        ...
 
-    def setting(self, id: str, default: bool | str) -> bool | str:
-        """Read one setting from the current callback snapshot."""
+    def setting(self, id: str, default: _SettingValue) -> _SettingValue:
+        """Read one setting from the current callback snapshot, as the type of `default`."""
+        ...
 
     def state_get(self, key: str) -> Any:
         """Read one value out of the extension's durable state."""
+        ...
 
     def state_put(self, key: str, value: Any) -> Any:
         """Write one JSON value into the extension's durable state."""
+        ...
 
     def state_del(self, key: str) -> Any:
         """Drop one key from the extension's durable state."""
+        ...
 
     def state_keys(self) -> Any:
         """List every key the extension's durable state holds."""
+        ...
 
     def log(self, level: str, message: str) -> Any:
         """Emit one engine log line at a level."""
+        ...
 
     def notify(self, text: str, level: str) -> Any:
         """Show one notification on the user's channel."""
+        ...
 
     def council_wake(self, options: Mapping[str, Any]) -> Mapping[str, Any]:
         """Publish to the bound session. Only an eligible managed subagent wakes itself."""
+        ...
 
     def shell(self, options: Mapping[str, Any]) -> Mapping[str, Any]:
         """Run one shell operation. Return the contract's result shape."""
+        ...
 
     def jailed_shell(self, options: Mapping[str, Any]) -> Mapping[str, Any]:
         """Run one shell op inside the workspace jail."""
+        ...
 
     def request_input(
         self,
         request_json: str,
         validator_arities_json: str,
-        run_validator: Callable[[str, str], str],
+        run_validator: Callable[[str, int, str, str], str],
     ) -> str:
         """Ask the human, and block until the answer settles or is cancelled."""
+        ...
 
     def live(self, envelope_json: str) -> str:
         """Open, patch, read or close a live view.
@@ -96,28 +113,34 @@ class Host(Protocol):
         An unchanged timeout returns is_open=True, timed_out=True, without view.
         Ordinary state reads and changed waits return the current view with seq.
         """
+        ...
 
     def activity(self, presentation: dict[str, Any]) -> bool:
         """Replace the running symbol's headline, summary, content and sections."""
+        ...
 
     def reveal_secret(self, handle: str) -> Any:
         """Resolve a `vis-secret:` handle to its plaintext."""
+        ...
 
     def forget_secret(self, handle: str) -> Any:
         """Drop the plaintext a secret handle stands for."""
+        ...
 
     def declare_env(self, declarations_json: str) -> str:
         """Resolve the environment variables the extension declared."""
+        ...
 
     def call_tool(
         self, tool: str, args: Sequence[Any], kwargs: Mapping[str, Any]
     ) -> Any:
         """Run one active session tool by the name `python_execution` calls."""
+        ...
 
 
-try:
-    _host  # noqa: B018, F821 — the host seeds this into the module dict before exec.
-except NameError:  # Installed from PyPI: no host in the room, so bring one.
+# The engine seeds `_host` into the module dict before exec.
+_host: Host
+if "_host" not in globals():  # Installed from PyPI: no host in the room, so bring one.
     from blockether.vis import _outside as outside
 
     _host = outside.host
@@ -253,7 +276,7 @@ def _tool_value(value):
     return value
 
 
-def _tool_data(value):
+def _tool_data(value) -> Any:
     """One argument as JSON data. A dataclass instance travels as its public fields."""
     if is_dataclass(value) and not isinstance(value, type):
         return {
@@ -333,7 +356,7 @@ def _bounded_text(value, limit, name):
         raise ValueError(f"{name} must be text of at most {limit} characters")
 
 
-def _wire_value(value):
+def _wire_value(value) -> Any:
     if isinstance(value, Mapping):
         return {key: _wire_value(item) for key, item in value.items()}
     if isinstance(value, (tuple, list)):
@@ -341,7 +364,7 @@ def _wire_value(value):
     return value
 
 
-def _freeze_config(value):
+def _freeze_config(value) -> Any:
     if isinstance(value, Mapping):
         if not all(isinstance(key, str) for key in value):
             raise TypeError("provider JSON keys must be strings")
@@ -359,6 +382,7 @@ def _freeze_config(value):
 
 class _ActivityBlock:
     __slots__ = ()
+    __dataclass_fields__: ClassVar[dict[str, Any]]  # Each subclass is a dataclass.
     type: ClassVar[str]
 
     def to_wire(self) -> dict[str, Any]:
@@ -510,7 +534,9 @@ class ActivityProgress(_ActivityBlock):
         if self.value is None and self.total is None:
             return
         if (
-            type(self.value) not in (int, float)
+            self.value is None
+            or self.total is None
+            or type(self.value) not in (int, float)
             or type(self.total) not in (int, float)
             or not math.isfinite(self.value)
             or not math.isfinite(self.total)
@@ -539,8 +565,9 @@ ActivityBlock: TypeAlias = (
 
 _ActivitySummaryFormat: TypeAlias = Literal["inline", "markdown"]
 _ActivityVerdict: TypeAlias = Literal["passed", "failed"]
-_SymbolTag: TypeAlias = Literal["observation", "mutation", "verification", "external"]
-_SYMBOL_TAGS = get_args(_SymbolTag)
+# The kind of work of one tool call. Annotate a tag in a variable with this type.
+SymbolTag: TypeAlias = Literal["observation", "mutation", "verification", "external"]
+_SYMBOL_TAGS = get_args(SymbolTag)
 
 
 @dataclass(frozen=True, slots=True)
@@ -762,9 +789,10 @@ def _activity_call(fn, activity):
         except Exception:
             pass  # Presentation must not alter the operation's result or error.
 
+    # Each branch declares `invoke`; only one of them runs.
     if inspect.iscoroutinefunction(fn):
 
-        async def invoke(*args, **kwargs):
+        async def invoke(*args, **kwargs):  # pyright: ignore[reportRedeclaration]
             if activity.show_start:
                 render("start", args, kwargs)
             try:
@@ -792,23 +820,24 @@ def _activity_call(fn, activity):
     return wraps(fn)(invoke)
 
 
-_registration = {"spec": None}
+_registration: dict[str, Any] = {"spec": None}
 
 
 @dataclass(frozen=True, slots=True, kw_only=True)
-class Setting:
+class Setting(Generic[_SettingValue]):
     """Declare a boolean or choice setting shared by the app and TUI.
 
     `scopes` allows any non-empty combination of global, project, group and session.
     Omitting it uses the contract's global-only default. A project extension exists
     only in its project, so there `global` means the whole project. The setting shows
     in its extension's own settings section. `value()` reads the current callback's
-    response snapshot. Outside Vis, it returns the declared default.
+    response snapshot. Its type follows `default`: `bool` for a boolean setting, `str`
+    for a choice setting. Outside Vis, it returns the declared default.
     """
 
     id: str
     label: str
-    default: bool | str
+    default: _SettingValue
     type: str = "boolean"
     choices: Sequence[str] = ()
     scopes: Sequence[str] | None = None
@@ -850,7 +879,7 @@ class Setting:
             spec["description"] = self.description
         return spec
 
-    def value(self) -> bool | str:
+    def value(self) -> _SettingValue:
         """Read this setting in the current callback without changing any scope."""
         return _host.setting(self.id, self.default)
 
@@ -1863,8 +1892,9 @@ def sequence(*, field: str) -> Callable[[_SequenceClass], _SequenceClass]:
             )
         if field not in {item.name for item in fields(cls)}:
             raise ValueError(f"sequence field {field!r} is not a dataclass field")
-        cls.__vis_sequence_field__ = field
-        return cls
+        # Pyright narrows `cls` to a plain dataclass type and cannot see the marker.
+        cls.__vis_sequence_field__ = field  # pyright: ignore[reportAttributeAccessIssue]
+        return cls  # pyright: ignore[reportReturnType]
 
     return decorate
 
@@ -1879,11 +1909,16 @@ class _MethodDecorator(Protocol):
     def __call__(self, actual: _Method) -> _Method: ...
 
 
+def _method_function(value: Any) -> Any:
+    """Return the function under a `staticmethod` or `classmethod`, else `value`."""
+    return value.__func__ if isinstance(value, (staticmethod, classmethod)) else value
+
+
 @overload
 def method(
     fn: _Method,
     *,
-    tag: _SymbolTag = "observation",
+    tag: SymbolTag = "observation",
     is_hidden: bool = False,
     activity: Activity | None = None,
 ) -> _Method: ...
@@ -1893,19 +1928,19 @@ def method(
 def method(
     fn: None = None,
     *,
-    tag: _SymbolTag = "observation",
+    tag: SymbolTag = "observation",
     is_hidden: bool = False,
     activity: Activity | None = None,
 ) -> _MethodDecorator: ...
 
 
 def method(
-    fn: _Method | None = None,
+    fn: Any = None,
     *,
-    tag: _SymbolTag = "observation",
+    tag: SymbolTag = "observation",
     is_hidden: bool = False,
     activity: Activity | None = None,
-) -> _Method | _MethodDecorator:
+) -> Any:
     """Describe a public method on an object exported through `Symbol`.
 
     Args:
@@ -1950,16 +1985,13 @@ def method(
     _activity_spec(activity)
 
     def _mark(actual: _Method) -> _Method:
-        declared = (
-            actual.__func__
-            if isinstance(actual, (staticmethod, classmethod))
-            else actual
-        )
+        declared = _method_function(actual)
         if not callable(declared):
             raise ValueError("vis.method(...) requires a callable method")
-        declared.__vis_symbol_tag__ = tag
-        declared.__vis_symbol_hidden__ = bool(is_hidden)
-        declared.__vis_symbol_activity__ = activity
+        # Pyright does not model attributes that code sets on a function.
+        declared.__vis_symbol_tag__ = tag  # pyright: ignore[reportFunctionMemberAccess]
+        declared.__vis_symbol_hidden__ = bool(is_hidden)  # pyright: ignore[reportFunctionMemberAccess]
+        declared.__vis_symbol_activity__ = activity  # pyright: ignore[reportFunctionMemberAccess]
         return actual
 
     return _mark if fn is None else _mark(fn)
@@ -1972,9 +2004,7 @@ def _public_members(obj):
         for name, raw in vars(cls).items():
             if name.startswith("_"):
                 continue
-            declared = (
-                raw.__func__ if isinstance(raw, (staticmethod, classmethod)) else raw
-            )
+            declared = _method_function(raw)
             candidates[name] = (
                 "method" if inspect.isroutine(declared) else "value",
                 declared,
@@ -2074,7 +2104,7 @@ class Symbol:
 
     fn: Callable[..., Any] | object
     name: str | None = None
-    tag: _SymbolTag = "observation"
+    tag: SymbolTag = "observation"
     is_hidden: bool = False
     activity: Activity | None = None
 
@@ -2184,7 +2214,7 @@ class ToolSpec:
 
     version: int
     name: str
-    tag: _SymbolTag
+    tag: SymbolTag
     description: str
     signature: str
     parameters: tuple[ParameterSpec, ...]
@@ -2223,7 +2253,7 @@ def _catalog_type(contract):
     )
 
 
-def _catalog_presentation(*, phase, result=None, error=None, **_):
+def _catalog_presentation(*, phase, result: Any = None, error=None, **_):
     if phase == "failure":
         return ActivityPresentation("Tool reference", str(error))
     if phase == "start":
@@ -2565,10 +2595,11 @@ def _provider_wire(value):
 
 class _ProviderValue:
     __slots__ = ()
+    __dataclass_fields__: ClassVar[dict[str, Any]]  # Each subclass is a dataclass.
 
     def to_wire(self) -> dict[str, ProviderJSON]:
         """Return fresh host data. Declared optional fields are omitted, not null."""
-        value = {
+        value: dict[str, ProviderJSON] = {
             f.name: _provider_wire(getattr(self, f.name))
             for f in fields(self)
             if f.name != "extra" and getattr(self, f.name) is not None
@@ -2839,13 +2870,14 @@ def _provider_callback(name, fn):
             raise TypeError(f"vis.Provider {name} returned an awaitable")
         if result is None or name in ("logout_fn", "on_selected_fn"):
             return None
-        expected = {
+        expected_types: dict[str, type[_ProviderValue]] = {
             "get_token_fn": ProviderCredential,
             "detect_fn": ProviderCredential,
             "refresh_token_fn": ProviderCredential,
             "status_fn": ProviderStatus,
             "limits_fn": ProviderLimits,
-        }.get(name)
+        }
+        expected = expected_types.get(name)
         if expected is not None:
             if not isinstance(result, expected):
                 raise TypeError(
@@ -3092,7 +3124,7 @@ class Shell(dict):
 
     def logs(self, offset=None, limit=None):
         # A NEGATIVE offset reads the last n LINES; a positive one is a byte cursor.
-        opts = {"op": "logs"}
+        opts: dict[str, Any] = {"op": "logs"}
         if offset is not None:
             opts["offset"] = int(offset)
         if limit is not None:
@@ -3152,7 +3184,8 @@ class _Fs:
 
     @staticmethod
     def _door():
-        import _vis_fs
+        # Only the engine's sandbox provides this module.
+        import _vis_fs  # pyright: ignore[reportMissingImports]
 
         return _vis_fs
 
@@ -3634,7 +3667,8 @@ class _Node:
 class _KeyedNode(_Node):
     """A node holding items the extension addresses by id: it can drop them."""
 
-    def remove(self, *item_ids):
+    def remove(self: _Node, *item_ids):
+        # Stat and Steps borrow this method, so `self` can be any node.
         # Ids as arguments or as one iterable, because a caller with a list
         # should not have to spread it.
         ids = (
@@ -4346,13 +4380,17 @@ class _LiveRecorder:
             yield node
             yield from _LiveRecorder._nodes(node.get("fields"))
 
-    def node(self, node_id):
-        """Return one materialized node by id, at any depth."""
+    def _open_view(self):
+        """Return the materialized view; a test must open one first."""
         if self._view is None:
             raise AssertionError("no test live view is open")
+        return self._view
+
+    def node(self, node_id):
+        """Return one materialized node by id, at any depth."""
         return next(
             node
-            for node in self._nodes(self._view.get("nodes"))
+            for node in self._nodes(self._open_view().get("nodes"))
             if node["id"] == node_id
         )
 
@@ -4408,7 +4446,7 @@ class _LiveRecorder:
                     return found
             return None
 
-        return find(self._view.get("nodes"))
+        return find(self._open_view().get("nodes"))
 
     def _apply(self, op):
         action = op["op"]
@@ -4417,10 +4455,9 @@ class _LiveRecorder:
             found = (
                 self._parent(op.get("after")) if op.get("after") is not None else None
             )
+            view = self._open_view()
             siblings, at = (
-                (self._view["nodes"], len(self._view["nodes"]))
-                if found is None
-                else found
+                (view["nodes"], len(view["nodes"])) if found is None else found
             )
             siblings.insert(at + (1 if found is not None else 0), node)
             return
@@ -4537,7 +4574,7 @@ class _LiveRecorder:
             for op in (envelope.get("patch") or {}).get("ops") or []:
                 self._apply(op)
             self._seq += 1
-            self._view["seq"] = self._seq
+            self._open_view()["seq"] = self._seq
             answer = {"view_id": self.view_id, "is_open": True, "seq": self._seq}
         elif action == "state":
             answer = {"view_id": self.view_id, "is_open": True, "view": self._view}
@@ -4684,9 +4721,11 @@ def _assert_catalog(
     mutation names. Test invocation, validation, IO and cancellation separately. Any and
     opaque types are allowed. Unresolved annotations fail with their path.
     """
+    roots = catalog.spec()
+    assert isinstance(roots, tuple), "Catalog.spec() lists the top-level specs"
     tools = tuple(
         tool
-        for spec in catalog.spec()
+        for spec in roots
         for tool in (spec.members if isinstance(spec, NamespaceSpec) else (spec,))
     )
     actual_names = [tool.name for tool in tools]

{vis_agent-0.2.32.dev7313 → vis_agent-0.2.32.dev7344}/src/blockether/vis/extension_package.py

@@ -18,6 +18,7 @@ import tomllib
 import uuid
 from http.client import HTTPException
 from pathlib import Path
+from typing import TYPE_CHECKING
 from urllib.error import HTTPError, URLError
 from urllib.parse import unquote, urlsplit
 from urllib.request import HTTPRedirectHandler, Request, build_opener
@@ -27,7 +28,9 @@ try:
     from packaging.specifiers import SpecifierSet
     from packaging.utils import canonicalize_name
     from packaging.version import Version
-except ImportError:
+except ImportError:  # The engine's Python can lack packaging; pip vendors a copy.
+    if TYPE_CHECKING:  # Type checkers see only the declared packaging dependency.
+        raise
     from pip._vendor.packaging.requirements import Requirement
     from pip._vendor.packaging.specifiers import SpecifierSet
     from pip._vendor.packaging.utils import canonicalize_name
@@ -961,6 +964,7 @@ def update(
     if subdirectory is None and not folder:
         folder = None
     active, current = _installed_repository(directory, repository, folder)
+    assert active is not None and current is not None  # A required lookup raises.
     name = current["name"]
     release = _select(
         _releases(current["repository_url"], current["subdirectory"]), version
@@ -1011,6 +1015,7 @@ def rollback(
     if subdirectory is None and not folder:
         folder = None
     active, current = _installed_repository(directory, repository, folder)
+    assert active is not None and current is not None  # A required lookup raises.
     name = current["name"]
     if version is not None:
         release = _select(
@@ -1356,8 +1361,7 @@ def sync(
     if not dry_run:
         directory.mkdir(parents=True, exist_ok=True)
     lock = directory / ".sync-lock"
-    if not dry_run:
-        fd = _acquire(lock)
+    fd = None if dry_run else _acquire(lock)
     try:
         records = _sync_records(directory)
         results = []
@@ -1381,7 +1385,8 @@ def sync(
                             _save_sync_records(directory, records)
                 elif dry_run:
                     unchanged = (
-                        _sync_owned(destination, current)
+                        current is not None
+                        and _sync_owned(destination, current)
                         and current["spec"] == spec
                         and not refresh
                         and not _tracks_latest(spec)

{vis_agent-0.2.32.dev7313 → vis_agent-0.2.32.dev7344}/src/blockether/vis/rooms.py

@@ -375,7 +375,7 @@ class RoomsClient:
         *,
         lease_seconds: int | None = None,
     ) -> int:
-        body = {"sessions": sessions}
+        body: dict[str, Any] = {"sessions": sessions}
         if lease_seconds is not None:
             body["lease_seconds"] = lease_seconds
         return self._request("POST", self._path(room_id, "/presence"), body)[

{vis_agent-0.2.32.dev7313 → vis_agent-0.2.32.dev7344}/src/blockether/vis/views.py

@@ -177,6 +177,7 @@ class ViewEvent:
             "view.close": "close_event",
         }[event_type]
         validate("view", definition, value)
+        payload: dict[str, Any]
         if event_type == "view.open":
             model = InputView if value["kind"] == "input" else LiveView
             document = model.from_wire(value["view"])

vis_agent-0.2.32.dev7344/tests/test_sdk_typing.py

@@ -0,0 +1,108 @@
+"""Regression coverage for SDK types under Pyright standard checks."""
+
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+import blockether.vis.extension as vis
+
+_SYMBOL_TAG_FIXTURE = """from typing import assert_type
+
+import blockether.vis.extension as vis
+
+
+def _knows(tag: vis.SymbolTag) -> bool:
+    try:
+        vis.method(tag=tag)
+    except ValueError:
+        return False
+    return True
+
+
+CHECK: vis.SymbolTag = "verification" if _knows("verification") else "observation"
+
+
+def bind(fn, *, tag: vis.SymbolTag = "observation"):
+    return vis.method(tag=tag)(fn)
+
+
+bind(print, tag=CHECK)
+assert_type(vis.Symbol(print, tag=CHECK).tag, vis.SymbolTag)
+UNKNOWN: vis.SymbolTag = "unknown"
+"""
+
+_SETTING_FIXTURE = """from typing import assert_type
+
+import blockether.vis.extension as vis
+
+ENABLED = vis.Setting(id="enabled", label="Desktop alerts", default=True)
+LEVEL = vis.Setting(
+    id="level", label="Level", default="fast", type="enum", choices=["fast", "slow"]
+)
+
+
+def start(*, enabled: bool) -> None: ...
+
+
+def context(env):
+    start(enabled=ENABLED.value())
+    assert_type(ENABLED, vis.Setting[bool])
+    assert_type(ENABLED.value(), bool)
+    assert_type(LEVEL.value(), str)
+"""
+
+
+def _pyright(tmp_path, *targets):
+    config = tmp_path / "pyrightconfig.json"
+    config.write_text(
+        json.dumps({"typeCheckingMode": "standard", "pythonVersion": "3.11"})
+    )
+    command = [
+        sys.executable,
+        "-m",
+        "pyright",
+        "--project",
+        str(config),
+        "--pythonpath",
+        sys.executable,
+        "--warnings",
+        "--outputjson",
+        *(str(target) for target in targets),
+    ]
+    return subprocess.run(command, capture_output=True, text=True, check=False)
+
+
+def test_sdk_sources_pass_pyright_standard(tmp_path):
+    # The SDK ships py.typed, so type checkers trust its annotations. Each
+    # standard-mode finding needs a fix or an explicit suppression (#315).
+    package = Path(vis.__file__).resolve().parent
+    result = _pyright(tmp_path, package)
+    assert result.returncode == 0, result.stdout + result.stderr
+    summary = json.loads(result.stdout)["summary"]
+    assert summary["filesAnalyzed"] == len(list(package.rglob("*.py")))
+
+
+def test_symbol_tag_types_tags_in_variables(tmp_path):
+    # A tag in a variable or a helper parameter needs a public type (#313).
+    # The alias still rejects a tag that Vis does not know.
+    fixture = tmp_path / "symbol_tag.py"
+    fixture.write_text(_SYMBOL_TAG_FIXTURE)
+    result = _pyright(tmp_path, fixture)
+    report = json.loads(result.stdout)
+    found = [
+        (item["range"]["start"]["line"], item["rule"])
+        for item in report["generalDiagnostics"]
+    ]
+    unknown = _SYMBOL_TAG_FIXTURE.splitlines().index(
+        'UNKNOWN: vis.SymbolTag = "unknown"'
+    )
+    assert found == [(unknown, "reportAssignmentType")], result.stdout
+
+
+def test_setting_value_has_the_type_of_its_default(tmp_path):
+    # A boolean setting reads a bool and a choice setting reads a str (#314).
+    fixture = tmp_path / "setting_value.py"
+    fixture.write_text(_SETTING_FIXTURE)
+    result = _pyright(tmp_path, fixture)
+    assert result.returncode == 0, result.stdout + result.stderr