vis-agent 0.2.38.dev7570__tar.gz → 0.2.39.dev7588__tar.gz

{vis_agent-0.2.38.dev7570 → vis_agent-0.2.39.dev7588}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vis-agent
-Version: 0.2.38.dev7570
+Version: 0.2.39.dev7588
 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.dev7570 → vis_agent-0.2.39.dev7588}/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.dev7570 → vis_agent-0.2.39.dev7588}/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.dev7570 → vis_agent-0.2.39.dev7588}/pyproject.toml

@@ -8,7 +8,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vis-agent"
-version = "0.2.38.dev7570"
+version = "0.2.39.dev7588"
 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.dev7570 → vis_agent-0.2.39.dev7588}/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 --------------------------------------------------------------
 
 
@@ -1332,12 +1436,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.dev7570 → vis_agent-0.2.39.dev7588}/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

vis_agent-0.2.39.dev7588/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.39.dev7588/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.dev7570 → vis_agent-0.2.39.dev7588}/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():