vis-agent 0.2.38.dev7568__tar.gz → 0.2.39__tar.gz

{vis_agent-0.2.38.dev7568 → vis_agent-0.2.39}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vis-agent
-Version: 0.2.38.dev7568
+Version: 0.2.39
 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.38.dev7568 → vis_agent-0.2.39}/contracts/schema/gateway.json

@@ -2732,6 +2732,10 @@
             "type": "string"
           }
         },
+        "change_error": {
+          "type": "string",
+          "description": "Present after a write when the owner's change hook failed. The value stays saved."
+        },
         "parent": {
           "type": "string",
           "description": "Id of the setting that this row belongs under."

{vis_agent-0.2.38.dev7568 → vis_agent-0.2.39}/contracts/schema/toggle.json

@@ -100,6 +100,9 @@
           "minItems": 1
         },
         "visible_fn": {},
+        "on_change_fn": {
+          "description": "Local callback that receives the id, old value, new value and scope once after a write changes the effective value."
+        },
         "scopes": {
           "type": "array",
           "items": {

{vis_agent-0.2.38.dev7568 → vis_agent-0.2.39}/pyproject.toml

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

{vis_agent-0.2.38.dev7568 → vis_agent-0.2.39}/src/blockether/vis/_contracts.py

@@ -41,6 +41,27 @@ def definition(name: str, key: str) -> dict[str, Any]:
     return schema(name)["$defs"][key]
 
 
+# An appended live item replaces the item with its id. The host fills these keys
+# when the item leaves them out; every other required key must come with it.
+_LIVE_ITEM_DEFAULTS = {"step": {"tone": "idle"}, "link": {"target_kind": "url"}}
+_LIVE_ITEMS = {"stats": "stat", "steps": "step", "rows": "row", "links": "link"}
+
+
+def live_items(key: str, items: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Return appended live items as the host keeps them; refuse a missing key."""
+    item = _LIVE_ITEMS[key]
+    required = definition("view", item)["required"]
+    result = []
+    for one in items:
+        one = {**_LIVE_ITEM_DEFAULTS.get(item, {}), **one}
+        if missing := [name for name in required if name not in one]:
+            raise ValueError(
+                f"{item} {one.get('id')}: {', '.join(missing)} is missing (required)"
+            )
+        result.append(one)
+    return result
+
+
 @lru_cache(maxsize=64)
 def _validator(name: str, definition: str):
     from jsonschema import Draft202012Validator, FormatChecker

{vis_agent-0.2.38.dev7568 → vis_agent-0.2.39}/src/blockether/vis/_outside.py

@@ -8,6 +8,7 @@ primes prompt values. With `VIS_OUTSIDE_NONINTERACTIVE=1`, prompts return
 
 from __future__ import annotations
 
+import base64
 import json
 import os
 import secrets
@@ -81,6 +82,22 @@ def call_tool(tool, args, kwargs):
     )
 
 
+def read_session(target):
+    """Refuse a session read without a bound Vis session and its database."""
+    raise Refused(
+        "vis.read_session needs a bound Vis session. Outside an extension, read the "
+        "session with the SDK client's get_session_transcript(session_id)."
+    )
+
+
+def list_sessions(search):
+    """Refuse a session search without a bound Vis session and its database."""
+    raise Refused(
+        "vis.list_sessions needs a bound Vis session. Outside an extension, list the "
+        "sessions with the SDK client's list_sessions()."
+    )
+
+
 # -- Where the outside host keeps things --------------------------------------
 
 
@@ -212,6 +229,93 @@ def forget_secret(handle):
     return _VAULT.pop(str(handle), None) is not None
 
 
+# -- Attachments ----------------------------------------------------------------
+# Outside Vis, no session stores artifacts. They stay in this process memory, so
+# an extension test can attach an artifact and read it back.
+
+_ARTIFACTS = []
+_ARTIFACT_BYTES = {}
+
+
+def attach(options):
+    """Store one artifact in memory and return its descriptor as JSON."""
+    data = base64.b64decode(options.get("base64") or "")
+    if not data:
+        raise ValueError("vis.attach: empty payload.")
+    name = options.get("filename") or "artifact"
+    media_type = (
+        options.get("media_type")
+        or options.get("media_type_hint")
+        or "application/octet-stream"
+    )
+    with _LOCK:
+        row = {
+            "id": uuid.uuid4().hex,
+            "source": "tool",
+            "filename": name,
+            "version": 1 + sum(1 for r in _ARTIFACTS if r["filename"] == name),
+            "media_type": media_type,
+            "kind": options.get("kind")
+            or ("image" if media_type.startswith("image/") else "file"),
+            "size": len(data),
+            "is_pending": True,
+            "audience": options.get("audience") or "both",
+            "commentable": options.get("commentable") is True,
+        }
+        _ARTIFACTS.append(row)
+        _ARTIFACT_BYTES[row["id"]] = data
+    return json.dumps(row)
+
+
+def list_attachments():
+    """List the in-memory artifact descriptors as JSON, oldest first."""
+    with _LOCK:
+        return json.dumps(_ARTIFACTS)
+
+
+def _artifact(caller, target, version):
+    # The same addressing as the engine: an id, or a filename with an optional
+    # version, where a negative version counts back from the latest one.
+    with _LOCK:
+        if version is None:
+            for row in _ARTIFACTS:
+                if row["id"] == target:
+                    return row
+        versions = sorted(
+            (r for r in _ARTIFACTS if r["filename"] == target),
+            key=lambda r: r["version"],
+        )
+    if versions:
+        if version is None:
+            return versions[-1]
+        if -len(versions) <= version <= -1:
+            return versions[version]
+        for row in versions:
+            if row["version"] == version:
+                return row
+        raise LookupError(f"{caller}: {target!r} has no version {version}.")
+    raise LookupError(f"{caller}: unknown id or filename {target!r}.")
+
+
+def get_attachment(target, version):
+    """Return one in-memory artifact descriptor as JSON."""
+    return json.dumps(_artifact("get_attachment", target, version))
+
+
+def read_attachment(target, version):
+    """Return the bytes of one in-memory artifact as base64 text."""
+    row = _artifact("read_attachment", target, version)
+    return base64.b64encode(_ARTIFACT_BYTES[row["id"]]).decode("ascii")
+
+
+def show_attachment(target, version):
+    """Accept an image. Outside Vis, no model request follows to show it to."""
+    row = _artifact("show_attachment", target, version)
+    if not row["media_type"].startswith("image/"):
+        raise ValueError(f"show_attachment: {row['filename']!r} is not an image.")
+    return [row["id"], row["filename"], row["media_type"], row["size"]]
+
+
 # -- Environment --------------------------------------------------------------
 
 
@@ -1037,9 +1141,10 @@ def _live_find(nodes, node_id):
     return None
 
 
-def _live_upsert(held, incoming):
+def _live_upsert(held, incoming, *, is_merged=False):
     # An item keeps the position it was first given: a row that updates in place
-    # is what makes a table readable while it fills.
+    # is what makes a table readable while it fills. The host replaces an item;
+    # only a group declaration merges onto the one before it.
     merged = list(held or [])
     for item in incoming or []:
         item_id = item.get("id") if isinstance(item, dict) else None
@@ -1051,7 +1156,7 @@ def _live_upsert(held, incoming):
         if at is None:
             merged.append(item)
         else:
-            merged[at] = {**merged[at], **item}
+            merged[at] = {**merged[at], **item} if is_merged else item
     return merged
 
 
@@ -1144,12 +1249,18 @@ def _live_apply(view, op):
             )
             node[key] = list(node.get(key) or []) + payload
         else:
+            try:
+                payload = _contracts.live_items(key, payload)
+            except ValueError as error:
+                raise Refused(str(error)) from None
             node[key] = _live_upsert(node.get(key), payload)
         if "groups" in op:
             # A table upserts its group DECLARATIONS in the same append that
             # carries the rows hanging under them, and a second declaration
             # merges onto the first: re-toning a head keeps its label.
-            node["groups"] = _live_upsert(node.get("groups"), op["groups"])
+            node["groups"] = _live_upsert(
+                node.get("groups"), op["groups"], is_merged=True
+            )
     elif name == "clear":
         node[_live_items_key(node, "clear")] = []
         if node.get("type") == "log":
@@ -1332,12 +1443,19 @@ _IMPLEMENTATIONS = {
     "jailed_shell": jailed_shell,
     "council_wake": council_wake,
     "call_tool": call_tool,
+    "read_session": read_session,
+    "list_sessions": list_sessions,
     "request_input": request_input,
     "live": live,
     "activity": lambda blocks: False,
     "reveal_secret": reveal_secret,
     "forget_secret": forget_secret,
     "declare_env": declare_env,
+    "attach": attach,
+    "list_attachments": list_attachments,
+    "get_attachment": get_attachment,
+    "read_attachment": read_attachment,
+    "show_attachment": show_attachment,
 }
 
 

{vis_agent-0.2.38.dev7568 → vis_agent-0.2.39}/src/blockether/vis/engine/_agent.py

@@ -377,6 +377,10 @@ class Agent:
         extensions: Iterable of `blockether.vis.extension.Extension` declarations.
             Their Python callables stay in your application and execute on the
             calling thread while you read, wait or iterate events.
+        tools: Optional iterable of Vis extension tool names for the conversation.
+            Names such as `"py.lint_code"` or `"py.repl_*"` keep only those tools of
+            the extensions they name. Names such as `"-py.repl_stop"` turn tools off.
+            Do not mix the two forms. The gateway refuses an unknown name.
 
     Construction does not start a process or connect. Session access, context
     entry, `send` or `run` starts the conversation. Closing the default agent stops
@@ -386,7 +390,8 @@ class Agent:
 
     Raises:
         TypeError: The supplied layer does not implement
-            `blockether.vis.engine.ExecutionLayer`, or an extension is unsupported.
+            `blockether.vis.engine.ExecutionLayer`, an extension is unsupported, or
+            `tools` is not an iterable of strings.
         ValueError: A project or extension declaration is invalid.
         FileNotFoundError: The local project does not exist.
         NotADirectoryError: The local project is not a directory.
@@ -398,10 +403,17 @@ class Agent:
         *,
         execution_layer: ExecutionLayer | None = None,
         extensions=(),
+        tools=None,
     ):
         from ._extensions import ClientExtensions
 
         self._extensions = ClientExtensions(extensions)
+        if tools is not None:
+            if isinstance(tools, str):
+                raise TypeError("tools must be an iterable of tool names, not a string")
+            tools = list(tools)
+            if not all(isinstance(name, str) for name in tools):
+                raise TypeError("tools must be an iterable of tool names")
         if execution_layer is not None and not isinstance(
             execution_layer, ExecutionLayer
         ):
@@ -411,6 +423,8 @@ class Agent:
             LocalEngine(root=project) if execution_layer is None else execution_layer
         )
         self._session_options = self.execution_layer.session_options(project)
+        if tools is not None:
+            self._session_options["tools"] = tools
         self.project = self._session_options["root"]
         self._session = None
         self._closed = False

{vis_agent-0.2.38.dev7568 → vis_agent-0.2.39}/src/blockether/vis/extension.py

@@ -9,10 +9,14 @@ from __future__ import annotations
 import __future__
 
 import ast
+import base64
 import builtins
 import inspect
+import io
 import json
 import math
+import mimetypes
+import os
 import sys
 import time
 from collections.abc import Callable, Mapping, Sequence
@@ -138,6 +142,34 @@ class Host(Protocol):
         """Run one active session tool by the name `python_execution` calls."""
         ...
 
+    def read_session(self, target: str | None) -> str:
+        """Read one whole session as the sandbox `read_session` does. Return JSON."""
+        ...
+
+    def list_sessions(self, search: str | None) -> str:
+        """List sessions as the sandbox `list_sessions` does. Return JSON."""
+        ...
+
+    def attach(self, options: Mapping[str, Any]) -> str:
+        """Store one artifact of the running block. Return its descriptor as JSON."""
+        ...
+
+    def list_attachments(self) -> str:
+        """List the session's artifact descriptors as JSON, pending ones included."""
+        ...
+
+    def get_attachment(self, target: str, version: int | None) -> str:
+        """Return the descriptor of one artifact as JSON."""
+        ...
+
+    def read_attachment(self, target: str, version: int | None) -> str:
+        """Return the bytes of one artifact as base64 text."""
+        ...
+
+    def show_attachment(self, target: str, version: int | None) -> Sequence[Any]:
+        """Queue a stored image for the next model request: id, filename, type, size."""
+        ...
+
 
 # The engine seeds `_host` into the module dict before exec.
 _host: Host
@@ -1007,6 +1039,9 @@ class Setting(Generic[_SettingValue]):
     for a choice setting. Outside Vis, it returns the declared default.
     `parent` names another setting of the same section. Settings shows this setting
     under that setting. Settings can nest at any depth.
+    `on_change(old, new, scope)` runs once after a person changes the setting in the
+    app or TUI and its effective value changes. `scope` is `global`, `project`, `group`
+    or `session`. Vis keeps the saved value if the hook raises, and shows the error.
     """
 
     id: str
@@ -1017,6 +1052,7 @@ class Setting(Generic[_SettingValue]):
     scopes: Sequence[str] | None = None
     description: str | None = None
     parent: str | None = None
+    on_change: Callable[[Any, Any, str], Any] | None = None
 
     def __post_init__(self):
         for name, value in (("scopes", self.scopes), ("choices", self.choices)):
@@ -1025,7 +1061,11 @@ class Setting(Generic[_SettingValue]):
             if not isinstance(value, (list, tuple)):
                 raise TypeError(f"Setting {name} must be a list or tuple")
             object.__setattr__(self, name, tuple(value))
-        spec = _host.setting_declaration(self._spec())
+        if self.on_change is not None and not callable(self.on_change):
+            raise TypeError("Setting on_change must be callable")
+        declaration = self._spec()
+        declaration.pop("on_change", None)
+        spec = _host.setting_declaration(declaration)
         object.__setattr__(self, "scopes", tuple(spec["scopes"]))
         if self.type == "boolean" and type(self.default) is not bool:
             raise ValueError("A boolean setting requires a boolean default")
@@ -1054,6 +1094,8 @@ class Setting(Generic[_SettingValue]):
             spec["description"] = self.description
         if self.parent is not None:
             spec["parent"] = self.parent
+        if self.on_change is not None:
+            spec["on_change"] = self.on_change
         return spec
 
     def value(self) -> _SettingValue:
@@ -3796,6 +3838,176 @@ def forget(handle):
     return bool(_host.forget_secret(str(handle)))
 
 
+# -- Attachments ----------------------------------------------------------------
+# An extension tool stores and reads artifacts like the sandbox `attach` verbs.
+# The engine binds each call to the python_execution block that runs the tool.
+
+_ATTACH_AUDIENCES = ("both", "user", "model")
+
+# Pillow encoders by filename suffix, as in the sandbox `attach` verb.
+_PIL_FORMATS = {
+    ".png": "PNG",
+    ".jpg": "JPEG",
+    ".jpeg": "JPEG",
+    ".gif": "GIF",
+    ".bmp": "BMP",
+    ".webp": "WEBP",
+    ".tif": "TIFF",
+    ".tiff": "TIFF",
+}
+
+
+def _attachment_row(row):
+    # The engine sends kebab-case keys; the SDK returns snake_case keys.
+    return {str(k).replace("-", "_"): v for k, v in dict(row).items()}
+
+
+def _attachment_source(source, filename):
+    """Return `(bytes, filename)` for a path, bytes, a figure or a Pillow image."""
+    if isinstance(source, (bytes, bytearray, memoryview)):
+        return bytes(source), str(filename) if filename else "artifact"
+    if hasattr(source, "savefig"):
+        buffer = io.BytesIO()
+        source.savefig(buffer, format="png")
+        return buffer.getvalue(), str(filename) if filename else "figure.png"
+    if hasattr(source, "save") and hasattr(source, "mode") and hasattr(source, "size"):
+        name = str(filename) if filename else "image.png"
+        buffer = io.BytesIO()
+        source.save(buffer, format=_PIL_FORMATS.get(Path(name).suffix.lower(), "PNG"))
+        return buffer.getvalue(), name
+    if not isinstance(source, (str, PathLike)):
+        raise TypeError(
+            "vis.attach: source must be a path, bytes, an image or a figure object, got "
+            + type(source).__name__
+        )
+    path = Path(os.path.expandvars(os.path.expanduser(os.fspath(source))))
+    if path.is_dir():
+        raise IsADirectoryError(f"vis.attach: {path} is a directory - attach one file")
+    try:
+        data = path.read_bytes()
+    except FileNotFoundError:
+        raise FileNotFoundError(f"vis.attach: no such file: {path}") from None
+    return data, str(filename) if filename else (path.name or "artifact")
+
+
+def _attachment_target(target, version):
+    if isinstance(target, Mapping):
+        target = target.get("id") or target.get("filename") or ""
+    if version is not None and (type(version) is not int):
+        raise TypeError("attachment version must be an integer")
+    return str(target), version
+
+
+def attach(
+    source,
+    filename=None,
+    *,
+    kind=None,
+    media_type=None,
+    label=None,
+    audience="both",
+    commentable=False,
+):
+    """Store an artifact as a durable attachment of the running block.
+
+    `source` is a path, bytes, a Matplotlib figure or a Pillow image. The engine
+    stores the artifact with the `python_execution` block that called this tool,
+    exactly like the sandbox `attach` verb. A second attachment under the same
+    `filename` is the next version of that artifact. `audience` is `both`, `user`
+    or `model`; a PDF or HTML document is for the user only. Set
+    `commentable=True` to let a person comment on this version.
+
+    Returns the descriptor dict: id, filename, version, media_type, kind, size,
+    audience and commentable. Every read function takes it as its target.
+    """
+    data, name = _attachment_source(source, filename)
+    if audience not in _ATTACH_AUDIENCES:
+        raise ValueError(
+            f"vis.attach: audience must be 'both', 'user' or 'model', got {audience!r}"
+        )
+    if not isinstance(commentable, bool):
+        raise TypeError("vis.attach: commentable must be a boolean")
+    if not data:
+        raise ValueError("vis.attach: empty payload.")
+    options = {
+        "base64": base64.b64encode(data).decode("ascii"),
+        "filename": name,
+        "media_type": media_type,
+        "media_type_hint": mimetypes.guess_type(name)[0],
+        "kind": kind,
+        "audience": audience,
+        "label": label,
+        "commentable": commentable,
+    }
+    payload = _host.attach({k: v for k, v in options.items() if v is not None})
+    return _attachment_row(json.loads(payload))
+
+
+def list_attachments(name=None):
+    """List the artifact descriptors of this session, oldest first.
+
+    The list includes the artifacts that the running block attached. With `name`,
+    it lists the versions of that one artifact.
+    """
+    rows = [_attachment_row(row) for row in json.loads(_host.list_attachments())]
+    if name is None:
+        return rows
+    versions = [row for row in rows if row.get("filename") == str(name)]
+    return sorted(versions, key=lambda row: int(row.get("version") or 1))
+
+
+def get_attachment(target, version=None):
+    """Return the descriptor of one artifact, without its bytes.
+
+    `target` is a filename, an id or a descriptor. A filename means the latest
+    version, unless you give `version`. A negative version counts back.
+    """
+    payload = _host.get_attachment(*_attachment_target(target, version))
+    return _attachment_row(json.loads(payload))
+
+
+def read_attachment(target, version=None):
+    """Return the bytes of one artifact. `target` works as in `get_attachment`."""
+    encoded = _host.read_attachment(*_attachment_target(target, version))
+    return base64.b64decode(encoded) if encoded else b""
+
+
+def show_attachment(target, version=None):
+    """Show a stored image to the model for the next request only.
+
+    `target` works as in `get_attachment`. Returns the id, filename, media_type
+    and size of the queued image.
+    """
+    shown = list(_host.show_attachment(*_attachment_target(target, version)))
+    return dict(zip(("id", "filename", "media_type", "size"), shown, strict=True))
+
+
+def read_session(target=None):
+    """Read one whole session, exactly as the sandbox `read_session` does.
+
+    Without `target`, it reads the session that runs the extension. `target` takes a
+    bare id, an unambiguous prefix or the copied `vis_session_id#<uuid>` marker. The
+    `introspection` toggle does not apply, because an extension is trusted code.
+
+    Returns the same string-keyed dict: session, current_turn, failures, diagnosis,
+    session_forks, turn_retries, usage and transcript.
+    """
+    return json.loads(_host.read_session(None if target is None else str(target)))
+
+
+def list_sessions(search=None):
+    """List sessions newest first, exactly as the sandbox `list_sessions` does.
+
+    With `search`, it runs the session search of the TUI and the Companion app. The
+    rows come in rank order: title, request, reply, then thinking, newest first in
+    each rank. Keep that order. The `introspection` toggle does not apply.
+
+    Returns string-keyed rows: id, channel, title, goal, turn_count, created_at and
+    modified_at. A match adds rank, the is_in_* flags and optional snippets.
+    """
+    return json.loads(_host.list_sessions(None if search is None else str(search)))
+
+
 # -- Live views ---------------------------------------------------------------
 # A form PAUSES a run to collect values; a live view REPORTS on work already
 # running. Nothing here blocks: a push crosses to the engine, every mounted
@@ -3908,8 +4120,9 @@ class Progress(_Node):
 
 
 class Stat(_Node):
-    def set(self, stat_id, value_text, label=None, tone=None):
-        # One counter of the strip, upserted by id.
+    def set(self, stat_id, value_text, label, tone=None):
+        # One counter of the strip, upserted by id. The View schema requires
+        # the label in each update.
         return self._op(
             "append",
             stats=[
@@ -3928,9 +4141,10 @@ class Stat(_Node):
 
 
 class Steps(_Node):
-    def set(self, step_id, tone=None, label=None, detail=None, value=None):
+    def set(self, step_id, label, tone=None, detail=None, value=None):
         # One step of the checklist, upserted by id: the same call marks it
-        # running and later done.
+        # running and later done. The View schema requires the label in each
+        # update.
         return self._op(
             "append",
             steps=[
@@ -4368,14 +4582,12 @@ class LiveView:
             value=value, done=done, total=total
         )
 
-    def stat(self, stat_id, value_text, label=None, tone=None):
-        return self._only("stat", "stat").set(
-            stat_id, value_text, label=label, tone=tone
-        )
+    def stat(self, stat_id, value_text, label, tone=None):
+        return self._only("stat", "stat").set(stat_id, value_text, label, tone=tone)
 
-    def step(self, step_id, tone=None, label=None, detail=None, value=None):
+    def step(self, step_id, label, tone=None, detail=None, value=None):
         return self._only("steps", "step").set(
-            step_id, tone=tone, label=label, detail=detail, value=value
+            step_id, label, tone=tone, detail=detail, value=value
         )
 
     def write(self, *lines: str | Sequence[str], tone: LogTone | None = None):
@@ -4597,7 +4809,7 @@ class _LiveRecorder:
             item = _LiveRecorder._copy(item)
             if item["id"] in positions:
                 at = positions[item["id"]]
-                result[at] = {**result[at], **item}
+                result[at] = item
             else:
                 positions[item["id"]] = len(result)
                 result.append(item)
@@ -4697,9 +4909,9 @@ class _LiveRecorder:
         elif action == "append":
             key = self._COLLECTION[node["type"]]
             incoming = self._copy(op.get(key) or [])
-            if node["type"] == "link":
-                for item in incoming:
-                    item.setdefault("target_kind", "url")
+            from blockether.vis import _contracts
+
+            incoming = _contracts.live_items(key, incoming)
             node[key] = self._upsert(node[key], incoming)
             if "groups" in op:
                 # `live/apply-append`: a group already declared KEEPS the keys the

{vis_agent-0.2.38.dev7568 → vis_agent-0.2.39}/tests/test_agent.py

@@ -276,6 +276,21 @@ def test_invalid_execution_layer_is_rejected_before_default_engine(local):
     local.assert_not_called()
 
 
+def test_tools_reach_the_new_conversation(local, tmp_path):
+    with engine.Agent(tmp_path, tools=("-py.lint_code", "py.repl_*")) as agent:
+        assert agent.session is agent.execution_layer.create_session.return_value
+        agent.execution_layer.create_session.assert_called_once_with(
+            root=str(tmp_path.resolve()), tools=["-py.lint_code", "py.repl_*"]
+        )
+
+
+@pytest.mark.parametrize("tools", ["py.lint_code", [1]])
+def test_tools_must_be_names(local, tmp_path, tools):
+    with pytest.raises(TypeError, match="tool names"):
+        engine.Agent(tmp_path, tools=tools)
+    local.assert_not_called()
+
+
 class Delivery(BaseModel):
     model_config = ConfigDict(extra="forbid")
 

vis_agent-0.2.39/tests/test_attachments.py

@@ -0,0 +1,109 @@
+"""`vis.attach` and the attachment readers, against the outside host."""
+
+import base64
+import json
+
+import blockether.vis.extension as vis
+import pytest
+from blockether.vis import _outside
+
+PNG = b"\x89PNG\r\n\x1a\n" + b"\0" * 16
+
+
+@pytest.fixture(autouse=True)
+def _empty_store(monkeypatch):
+    monkeypatch.setattr(_outside, "_ARTIFACTS", [])
+    monkeypatch.setattr(_outside, "_ARTIFACT_BYTES", {})
+    monkeypatch.setattr(vis, "_host", _outside.host)
+
+
+def test_attach_stores_a_path_and_returns_its_descriptor(tmp_path):
+    source = tmp_path / "report.csv"
+    source.write_text("a,b\n1,2\n", encoding="utf-8")
+
+    row = vis.attach(source, label="Totals", commentable=True)
+
+    assert row["filename"] == "report.csv"
+    assert row["version"] == 1
+    assert row["media_type"] == "text/csv"
+    assert row["kind"] == "file"
+    assert row["size"] == 8
+    assert row["commentable"] is True
+    assert vis.read_attachment(row) == b"a,b\n1,2\n"
+
+
+def test_same_filename_adds_a_version_and_targets_resolve_it():
+    first = vis.attach(PNG, "chart.png")
+    second = vis.attach(PNG + b"x", "chart.png", audience="user")
+
+    assert second["version"] == 2
+    assert second["kind"] == "image"
+    assert [r["version"] for r in vis.list_attachments("chart.png")] == [1, 2]
+    assert vis.get_attachment("chart.png")["id"] == second["id"]
+    assert vis.get_attachment("chart.png", version=-2)["id"] == first["id"]
+    assert vis.get_attachment(first["id"])["version"] == 1
+    assert vis.read_attachment("chart.png", 1) == PNG
+    assert vis.show_attachment(second) == {
+        "id": second["id"],
+        "filename": "chart.png",
+        "media_type": "image/png",
+        "size": len(PNG) + 1,
+    }
+
+
+def test_attach_sends_one_options_map_to_the_host(monkeypatch):
+    sent = []
+
+    class Host:
+        def attach(self, options):
+            sent.append(options)
+            return json.dumps(
+                {"id": "a1", "filename": options["filename"], "media-type": "x/y"}
+            )
+
+    monkeypatch.setattr(vis, "_host", Host())
+
+    # `.txt` maps to text/plain on every Python version; `.md` does not before 3.13.
+    assert vis.attach(b"data", "notes.txt", media_type="text/markdown") == {
+        "id": "a1",
+        "filename": "notes.txt",
+        "media_type": "x/y",
+    }
+    assert sent == [
+        {
+            "base64": base64.b64encode(b"data").decode("ascii"),
+            "filename": "notes.txt",
+            "media_type": "text/markdown",
+            "media_type_hint": "text/plain",
+            "audience": "both",
+            "commentable": False,
+        }
+    ]
+
+
+def test_attach_refuses_wrong_sources_and_options(tmp_path):
+    with pytest.raises(TypeError, match="source must be a path"):
+        vis.attach(object())
+    with pytest.raises(IsADirectoryError):
+        vis.attach(tmp_path)
+    with pytest.raises(FileNotFoundError, match="no such file"):
+        vis.attach(tmp_path / "missing.png")
+    with pytest.raises(ValueError, match="audience"):
+        vis.attach(PNG, "a.png", audience="everyone")
+    with pytest.raises(TypeError, match="commentable"):
+        vis.attach(PNG, "a.png", commentable="yes")
+    with pytest.raises(ValueError, match="empty payload"):
+        vis.attach(b"", "a.png")
+
+
+def test_readers_name_an_unknown_target_and_a_non_image():
+    vis.attach(b"text", "notes.txt")
+
+    with pytest.raises(LookupError, match="unknown id or filename"):
+        vis.get_attachment("other.txt")
+    with pytest.raises(LookupError, match="has no version 3"):
+        vis.read_attachment("notes.txt", 3)
+    with pytest.raises(ValueError, match="not an image"):
+        vis.show_attachment("notes.txt")
+    with pytest.raises(TypeError, match="version must be an integer"):
+        vis.get_attachment("notes.txt", "1")

{vis_agent-0.2.38.dev7568 → vis_agent-0.2.39}/tests/test_live_primitives.py

@@ -358,3 +358,28 @@ def test_a_group_arranging_nothing_is_refused_where_it_was_written():
     ):
         with pytest.raises(ValueError, match="at least one node"):
             build()
+
+
+@pytest.mark.parametrize("host_kind", ["outside", "recorder"])
+def test_stat_and_step_updates_carry_the_label_the_schema_requires(
+    monkeypatch, host_kind
+):
+    # The evals watch view sent a counter update without its label, and the host
+    # refused it. The recorder now refuses the same patch, as the View schema says.
+    host = (
+        _outside.host if host_kind == "outside" else vis.testing.LiveRecorder(vis._host)
+    )
+    monkeypatch.setattr(vis, "_host", host)
+    nodes = [
+        vis.stat("counts", stats=[{"id": "ok", "label": "Passed", "value_text": "0"}]),
+        vis.steps("plan", steps=[{"id": "build", "label": "Build"}]),
+    ]
+    with vis.live("Counts", nodes, flush_ms=0) as view:
+        with pytest.raises((ValueError, _outside.Refused), match="label"):
+            view["counts"]._op("append", stats=[{"id": "ok", "value_text": "1"}])
+        view["counts"].set("ok", "2", "Passed")
+        view["plan"].set("build", "Build", tone="ok")
+        counts, plan = view.state()["nodes"]
+        stats, steps = counts["stats"], plan["steps"]
+        assert stats == [{"id": "ok", "label": "Passed", "value_text": "2"}]
+        assert steps[0]["label"] == "Build" and steps[0]["tone"] == "ok"

vis_agent-0.2.39/tests/test_read_session.py

@@ -0,0 +1,55 @@
+"""`vis.read_session` and `vis.list_sessions` use the canonical host session reads."""
+
+from __future__ import annotations
+
+import json
+
+import blockether.vis.extension as vis
+import pytest
+from blockether.vis import _outside
+
+
+def test_answers_the_host_read_as_one_string_keyed_dict(monkeypatch):
+    targets = []
+    data = {
+        "session": {"id": "6fccb4a2-bf20-448c-ac4f-9d170983c0f3"},
+        "transcript": {"turns": [{"position": 1, "user_request": "Fix the typo."}]},
+    }
+
+    def read_session(target):
+        targets.append(target)
+        return json.dumps(data)
+
+    monkeypatch.setattr(vis._host, "read_session", read_session)
+    assert vis.read_session() == data
+    assert vis.read_session("vis_session_id#6fccb4a2") == data
+    assert targets == [None, "vis_session_id#6fccb4a2"]
+
+
+def test_answers_the_host_search_rows_in_their_rank_order(monkeypatch):
+    searches = []
+    rows = [
+        {"id": "b", "title": "Fix the typo", "rank": 0, "is_in_title": True},
+        {"id": "a", "title": "Release", "rank": 1, "is_in_request": True},
+    ]
+
+    def list_sessions(search):
+        searches.append(search)
+        return json.dumps(rows)
+
+    monkeypatch.setattr(vis._host, "list_sessions", list_sessions)
+    assert vis.list_sessions() == rows
+    assert vis.list_sessions(search="typo") == rows
+    assert searches == [None, "typo"]
+
+
+@pytest.mark.parametrize(
+    "call, message",
+    [
+        (vis.read_session, "vis.read_session needs a bound Vis session"),
+        (vis.list_sessions, "vis.list_sessions needs a bound Vis session"),
+    ],
+)
+def test_refuses_outside_a_vis_session(call, message):
+    with pytest.raises(_outside.Refused, match=message):
+        call()

{vis_agent-0.2.38.dev7568 → vis_agent-0.2.39}/tests/test_scoped_settings.py

@@ -68,6 +68,23 @@ def test_parent_nests_a_setting():
         vis.Setting(id="test_detail", label="Test detail", default=False, parent=" ")
 
 
+# Regression for #369: a setting declares a change hook that the host calls.
+def test_on_change_declares_a_callable_hook():
+    def record(old, new, scope):
+        return None
+
+    plain = vis.Setting(id="test_feature", label="Test feature", default=True)
+    hooked = vis.Setting(
+        id="test_feature", label="Test feature", default=True, on_change=record
+    )
+    assert "on_change" not in plain._spec()
+    assert hooked._spec()["on_change"] is record
+    with pytest.raises(TypeError):
+        vis.Setting(
+            id="test_feature", label="Test feature", default=True, on_change="record"
+        )
+
+
 # Regression for #322 and #323: a 300-character description is valid, and a
 # longer one names the setting, the field, the rule and the limit.
 def test_description_limit_and_actionable_error():