vis-agent 0.2.35.dev7411__tar.gz → 0.2.37__tar.gz

{vis_agent-0.2.35.dev7411 → vis_agent-0.2.37}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vis-agent
-Version: 0.2.35.dev7411
+Version: 0.2.37
 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.35.dev7411 → vis_agent-0.2.37}/contracts/schema/gateway.json

@@ -1779,7 +1779,7 @@
         "objective": {
           "type": "string",
           "minLength": 1,
-          "maxLength": 8192,
+          "maxLength": 44000,
           "pattern": "\\S"
         },
         "status": {

{vis_agent-0.2.35.dev7411 → vis_agent-0.2.37}/contracts/schema/toggle.json

@@ -46,7 +46,7 @@
         "description": {
           "type": "string",
           "minLength": 1,
-          "maxLength": 100,
+          "maxLength": 300,
           "pattern": "^[^\\r\\n]+$"
         },
         "default": {},

{vis_agent-0.2.35.dev7411 → vis_agent-0.2.37}/pyproject.toml

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

{vis_agent-0.2.35.dev7411 → vis_agent-0.2.37}/src/blockether/vis/_contracts.py

@@ -74,16 +74,62 @@ def _json_value(item):
     )
 
 
+def _problem(error) -> str:
+    """One readable line for a schema error: field, rule and limit, never the value."""
+    field = ".".join(str(part) for part in error.absolute_path) or "declaration"
+    rule, limit = error.validator, error.validator_value
+    if rule in ("maxLength", "minLength"):
+        bound = "maximum" if rule == "maxLength" else "minimum"
+        fix = f" Shorten the {field}." if rule == "maxLength" else ""
+        return (
+            f"{field} is {len(error.instance)} characters; {bound} is {limit} ({rule})."
+            + fix
+        )
+    if rule == "required":
+        missing = ", ".join(key for key in limit if key not in error.instance)
+        return f"{missing} is missing (required)."
+    if rule == "enum":
+        return f"{field} must be one of: {', '.join(map(str, limit))} (enum)."
+    if rule == "pattern":
+        if (
+            limit
+            == definition("toggle", "contribution")["properties"]["description"][
+                "pattern"
+            ]
+        ):
+            return f"{field} must be one line without line breaks (pattern)."
+        return f"{field} does not match the pattern {limit} (pattern)."
+    return f"{field} breaks the {rule} rule."
+
+
+def problems(name: str, definition: str, value: Any) -> list[str]:
+    """Readable rule failures of `value`, one line for each. Empty when it is valid.
+
+    Each line names the field, the rule and its limit. It never echoes the value.
+    """
+    if not _json_value(value):
+        return ["the value is not JSON data."]
+    errors = _validator(name, definition).iter_errors(value)
+    return [
+        _problem(error)
+        for error in sorted(errors, key=lambda e: list(map(str, e.absolute_path)))
+    ]
+
+
 def validate(name: str, definition: str, value: Any) -> Any:
     """Validate portable JSON data, returning it or raising a payload-free ValueError.
 
-    Schemas resolve only from the installed package. Runtime lifecycle, IO and
+    The error names each failed field, rule and limit, never the value. Schemas
+    resolve only from the installed package. Runtime lifecycle, IO and
     authorization belong to the engine, not JSON Schema.
     """
     try:
-        valid = _json_value(value) and _validator(name, definition).is_valid(value)
+        found = problems(name, definition, value)
     except (RecursionError, TypeError, ValueError):
-        valid = False
-    if not valid:
-        raise ValueError(f"invalid {name}.{definition} contract")
+        found = [""]
+    if found:
+        detail = " ".join(problem for problem in found if problem)
+        raise ValueError(
+            f"invalid {name}.{definition} contract" + (f": {detail}" if detail else "")
+        )
     return value

{vis_agent-0.2.35.dev7411 → vis_agent-0.2.37}/src/blockether/vis/_outside.py

@@ -91,13 +91,20 @@ def workspace_root():
 
 def setting_declaration(spec):
     """Use the package's own JSON Schemas for outside-host declarations."""
-    from ._contracts import definition, validate
+    from ._contracts import definition, problems, validate
 
     spec = dict(spec)
     spec.setdefault(
         "scopes",
         definition("toggle", "contribution")["properties"]["scopes"]["default"],
     )
+    found = problems("toggle", "contribution", spec)
+    if found:
+        name = spec.get("id")
+        label = (
+            f"Invalid setting {name}" if isinstance(name, str) else "Invalid setting"
+        )
+        raise ValueError(f"{label}: {' '.join(found)}")
     return validate("toggle", "contribution", spec)
 
 

{vis_agent-0.2.35.dev7411 → vis_agent-0.2.37}/src/blockether/vis/engine/_client.py

@@ -3251,8 +3251,8 @@ class Session:
         replies. The last iteration can run its tools, and then the limit blocks
         the next model request. Token usage is recorded only as a statistic.
         """
-        if not isinstance(objective, str) or not 1 <= len(objective.strip()) <= 8192:
-            raise ValueError("objective must contain 1–8192 characters")
+        if not isinstance(objective, str) or not 1 <= len(objective.strip()) <= 44000:
+            raise ValueError("objective must contain 1–44000 characters")
         if iteration_budget is not None and (
             type(iteration_budget) is not int
             or not 1 <= iteration_budget <= 9007199254740991

{vis_agent-0.2.35.dev7411 → vis_agent-0.2.37}/src/blockether/vis/extension.py

@@ -1388,10 +1388,11 @@ def _call_arguments(fn, args, kwargs):
     An argument crosses the host boundary as JSON, so a record arrives as a dict of its
     public fields. A parameter annotated with a dataclass gets that dataclass back,
     built through its constructor. This also works inside a union, list, tuple, set or
-    dict annotation (Blockether/vis#289). Annotations resolve statically, as for tool
-    contracts. A value that does not fit its annotation stays as it arrived. So does
-    every argument of a call that the signature cannot bind: the call itself reports
-    that mistake.
+    dict annotation (Blockether/vis#289). One bare string for a sequence of strings
+    becomes one item, not one item for each character (Blockether/vis#324).
+    Annotations resolve statically, as for tool contracts. A value that does not fit
+    its annotation stays as it arrived. So does every argument of a call that the
+    signature cannot bind: the call itself reports that mistake.
     """
     try:
         # A wrapper around a bound method must not unwrap past the binding.
@@ -1561,9 +1562,10 @@ def _holds_record(shape):
 def _rebuilt_value(shape, value):
     """Return `value` with the records that `shape` expects rebuilt.
 
+    One bare string for a sequence of strings becomes that sequence with one item.
     A value that does not fit stays as is.
     """
-    if not _holds_record(shape):
+    if not (_holds_record(shape) or isinstance(value, str)):
         return value
     result = _fitted_argument(shape, value)
     return value if result is _UNFIT else result
@@ -1588,7 +1590,11 @@ def _fitted_argument(shape, value):
     if kind == "record":
         return _rebuilt_record(shape[1], value, shape[2])
     if kind == "union":
-        for member in shape[1]:
+        members = shape[1]
+        if isinstance(value, str):
+            # A member that takes the string as it is wins over one that wraps it.
+            members = sorted(members, key=lambda member: member[0] == "sequence")
+        for member in members:
             result = _fitted_argument(member, value)
             if result is not _UNFIT:
                 return result
@@ -1599,6 +1605,13 @@ def _fitted_argument(shape, value):
         if not _holds_record(shape):
             return value
         return {key: _rebuilt_value(shape[1], item) for key, item in value.items()}
+    if kind == "sequence" and isinstance(value, str):
+        # A string is a sequence of its characters; the caller named one item. An
+        # item of any type also takes the whole string, so it stays as it is.
+        if shape[2] in (("any",), ("plain", object)):
+            return _UNFIT
+        item = _fitted_argument(shape[2], value)
+        return _UNFIT if item is _UNFIT else shape[1]((item,))
     if not isinstance(value, (list, tuple)):
         return _UNFIT
     if kind == "fixed":

{vis_agent-0.2.35.dev7411 → vis_agent-0.2.37}/src/blockether/vis/extension_package.py

@@ -954,6 +954,59 @@ def install(
     return _admit(source, directory, subdirectory, revision, vis_version, release)
 
 
+def _replace_managed(directory, active, current, release, vis_version):
+    """Activate a managed version and keep its sync ownership in the same operation."""
+    name = current["name"]
+    lock = directory / ".sync-lock"
+    fd = _acquire(lock)
+    try:
+        records = _sync_records(directory)
+        owned = records.get(name)
+        destination = _destination(directory, name)
+        if owned is not None and not _sync_owned(destination, owned):
+            raise ValueError(
+                "Existing extension was changed externally; no files replaced"
+            )
+        spec = _sync_spec(owned["spec"]) if owned is not None else None
+        previous_target = str(active)
+        snapshot = destination.parent / release["version"]
+        receipt_path = snapshot / "receipt.json"
+        previous_receipt = receipt_path.read_bytes() if receipt_path.is_file() else None
+        result = _admit(
+            current["repository_url"],
+            directory,
+            current["subdirectory"],
+            release["revision"],
+            vis_version,
+            release,
+            name,
+            active.name,
+        )
+        if spec is None:
+            return result
+        # Configuration pins remain authoritative on the next reconciliation.
+        if spec["revision"] is not None:
+            spec["revision"] = result["revision"]
+        elif spec["version"] not in (None, LATEST):
+            spec["version"] = result["version"]
+        try:
+            _save_sync_records(
+                directory,
+                {
+                    **records,
+                    name: {"spec": spec, "target": result["path"], "result": result},
+                },
+            )
+        except BaseException:
+            _restore_saved_link(directory, name, result["path"], previous_target)
+            if previous_receipt is not None:
+                receipt_path.write_bytes(previous_receipt)
+            raise
+        return result
+    finally:
+        _release(lock, fd)
+
+
 def update(
     source, directory, trust=False, version=None, vis_version=None, subdirectory=None
 ):
@@ -988,16 +1041,7 @@ def update(
         }
     if Version(release["version"]) == Version(current["version"]):
         raise ValueError("A published version cannot change its approved commit")
-    return _admit(
-        current["repository_url"],
-        directory,
-        current["subdirectory"],
-        release["revision"],
-        vis_version,
-        release,
-        name,
-        active.name,
-    )
+    return _replace_managed(directory, active, current, release, vis_version)
 
 
 def rollback(
@@ -1016,7 +1060,6 @@ def rollback(
         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(
             _releases(current["repository_url"], current["subdirectory"]), version
@@ -1031,24 +1074,15 @@ def rollback(
             raise ValueError(
                 "No previous installation; choose an approved older --version"
             )
-        release = _receipt(active.parent / _version(previous), name)
+        release = _receipt(active.parent / _version(previous), current["name"])
         if (
             release.get("repository_url") != current["repository_url"]
             or release.get("subdirectory") != current["subdirectory"]
-            or release.get("name") != name
+            or release.get("name") != current["name"]
             or not re.fullmatch(r"[0-9a-f]{40}", release.get("revision", ""))
         ):
             raise ValueError("Invalid previous package receipt")
-    return _admit(
-        current["repository_url"],
-        directory,
-        current["subdirectory"],
-        release["revision"],
-        vis_version,
-        release,
-        name,
-        active.name,
-    )
+    return _replace_managed(directory, active, current, release, vis_version)
 
 
 def _sync_spec(spec):

{vis_agent-0.2.35.dev7411 → vis_agent-0.2.37}/tests/test_contracts.py

@@ -178,6 +178,12 @@ def test_payload_free_validation():
         with pytest.raises(ValueError) as error:
             _contracts.validate("activity", "declaration", bad)
         assert "do-not-echo" not in str(error.value)
+    with pytest.raises(
+        ValueError, match=r": label does not match the pattern .* \(pattern\)"
+    ):
+        _contracts.validate(
+            "activity", "declaration", {"presenter": "tests", "label": "one\ntwo"}
+        )
     with pytest.raises(ValueError):
         _contracts.validate("view", "missing-definition", {})
 

{vis_agent-0.2.35.dev7411 → vis_agent-0.2.37}/tests/test_extension_package.py

@@ -1075,6 +1075,107 @@ def test_sync_pins_updates_refresh_and_rollback(releases):
     )
 
 
+def test_explicit_update_and_rollback_keep_sync_ownership(releases):
+    metadata, target, _ = releases
+    newer = metadata.pop(1)
+    configured = {
+        "vis-greeter": {"source": REPOSITORY, "subdirectory": "plugins/greeting"}
+    }
+    package.sync(configured, target, trust=True)
+    metadata.append(newer)
+    package.update(REPOSITORY, target, trust=True)
+    updated = package.sync(configured, target, trust=True)[0]
+    assert (updated["status"], updated.get("version")) == ("cached", "1.1.0")
+    package.rollback(REPOSITORY, target, trust=True)
+    restored = package.sync(configured, target, trust=True)[0]
+    assert (restored["status"], restored.get("version")) == ("cached", "1.0.0")
+
+
+@pytest.mark.parametrize("operation", ["update", "rollback"])
+def test_managed_activation_restores_ownership_when_sync_receipt_write_fails(
+    releases, monkeypatch, operation
+):
+    metadata, target, _ = releases
+    newer = metadata.pop(1)
+    configured = {
+        "vis-greeter": {"source": REPOSITORY, "subdirectory": "plugins/greeting"}
+    }
+    package.sync(configured, target, trust=True)
+    metadata.append(newer)
+    if operation == "rollback":
+        package.update(REPOSITORY, target, trust=True)
+    pointer = target / "vis-greeter/current"
+    previous_target = pointer.resolve()
+    previous_records = (target / ".sync.json").read_bytes()
+    receipt_path = target / "vis-greeter/1.0.0/receipt.json"
+    previous_receipt = receipt_path.read_bytes()
+
+    def fail(*_):
+        raise OSError("Fixture receipt write failure")
+
+    monkeypatch.setattr(package, "_save_sync_records", fail)
+    with pytest.raises(OSError, match="Fixture receipt write failure"):
+        getattr(package, operation)(REPOSITORY, target, trust=True)
+    assert pointer.resolve() == previous_target
+    assert (target / ".sync.json").read_bytes() == previous_records
+    assert receipt_path.read_bytes() == previous_receipt
+    assert package._sync_owned(pointer, package._sync_records(target)["vis-greeter"])
+    assert package.sync(configured, target, trust=True)[0]["status"] == "cached"
+
+
+@pytest.mark.parametrize("operation", ["update", "rollback"])
+def test_managed_activation_refuses_an_externally_changed_sync_pointer(
+    releases, operation
+):
+    metadata, target, _ = releases
+    newer = metadata.pop(1)
+    configured = {
+        "vis-greeter": {"source": REPOSITORY, "subdirectory": "plugins/greeting"}
+    }
+    package.sync(configured, target, trust=True)
+    metadata.append(newer)
+    package.update(REPOSITORY, target, trust=True)
+    pointer = target / "vis-greeter/current"
+    pointer.unlink()
+    pointer.symlink_to("1.0.0")
+    before = (target / ".sync.json").read_bytes()
+    kwargs = {"version": "1.1.0"} if operation == "update" else {}
+    with pytest.raises(ValueError):
+        getattr(package, operation)(REPOSITORY, target, trust=True, **kwargs)
+    assert pointer.resolve().name == "1.0.0"
+    assert (target / ".sync.json").read_bytes() == before
+
+
+@pytest.mark.parametrize("pin", ["version", "revision"])
+def test_explicit_update_does_not_override_a_configuration_pin(releases, pin):
+    metadata, target, _ = releases
+    spec = {"source": REPOSITORY, "subdirectory": "plugins/greeting"}
+    spec[pin] = metadata[0][pin]
+    configured = {"vis-greeter": spec}
+    package.sync(configured, target, trust=True)
+    package.update(REPOSITORY, target, trust=True)
+    restored = package.sync(configured, target, trust=True)[0]
+    assert (restored["status"], restored.get("version")) == ("updated", "1.0.0")
+
+
+def test_update_validates_sync_spec_before_changing_the_active_version(releases):
+    metadata, target, _ = releases
+    newer = metadata.pop(1)
+    configured = {
+        "vis-greeter": {"source": REPOSITORY, "subdirectory": "plugins/greeting"}
+    }
+    package.sync(configured, target, trust=True)
+    metadata.append(newer)
+    records = package._sync_records(target)
+    records["vis-greeter"]["spec"] = {}
+    package._save_sync_records(target, records)
+    before = (target / ".sync.json").read_bytes()
+    with pytest.raises(ValueError, match="source"):
+        package.update(REPOSITORY, target, trust=True)
+    assert (target / "vis-greeter/current").resolve().name == "1.0.0"
+    assert (target / ".sync.json").read_bytes() == before
+
+
 def test_sync_latest_tracks_approved_stable_releases(releases):
     metadata, target, commands = releases
     newer = metadata.pop(1)

{vis_agent-0.2.35.dev7411 → vis_agent-0.2.37}/tests/test_goals.py

@@ -40,7 +40,7 @@ def test_goal_uses_slash_turn(budget):
     [
         ("", None),
         (" ", None),
-        ("x" * 8193, None),
+        ("x" * 44001, None),
         (None, None),
         ("work", 0),
         ("work", -1),

{vis_agent-0.2.35.dev7411 → vis_agent-0.2.37}/tests/test_scoped_settings.py

@@ -68,6 +68,32 @@ def test_parent_nests_a_setting():
         vis.Setting(id="test_detail", label="Test detail", default=False, parent=" ")
 
 
+# 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():
+    def mode(description):
+        return vis.Setting(
+            id="steering_mode",
+            label="Steering mode",
+            type="enum",
+            choices=["vibe", "control"],
+            default="vibe",
+            description=description,
+        )
+
+    assert mode("x" * 300).description == "x" * 300
+    with pytest.raises(ValueError) as error:
+        mode("x" * 301)
+    assert str(error.value) == (
+        "Invalid setting steering_mode: description is 301 characters; "
+        "maximum is 300 (maxLength). Shorten the description."
+    )
+    with pytest.raises(ValueError, match="one line without line breaks"):
+        mode("two\nlines")
+    with pytest.raises(ValueError, match="minimum is 1"):
+        mode("")
+
+
 def test_application_bridge_rejects_host_only_settings_before_connecting():
     declaration = vis.Extension(
         name="Settings test",

vis_agent-0.2.37/tests/test_text_list_arguments.py

@@ -0,0 +1,89 @@
+"""Regression coverage for #324: one bare string for a list of strings is one item."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Annotated, Literal, Optional
+
+import blockether.vis.extension as vis
+
+
+class Tools:
+    """The parameter shapes of the `py.*` and `clj.*` language tools."""
+
+    def lint_code(
+        self,
+        paths: Annotated[Sequence[str], "Files or directories to lint."] = (),
+        *,
+        cwd: str = "",
+        namespaces: Annotated[Sequence[str], "Test namespaces to run."] = (),
+    ) -> tuple:
+        return tuple(paths), tuple(namespaces)
+
+
+def rebuilt(fn, *args, **kwargs):
+    return vis._call_arguments(fn, list(args), kwargs)
+
+
+def test_bare_string_for_a_string_sequence_is_one_item():
+    # Regression for Blockether/vis#324: `py.lint_code("/src/app.py")` named one
+    # path for each character, and `/` made the lint walk the whole filesystem.
+    tools = Tools()
+    args, kwargs = rebuilt(tools.lint_code, "/src/app.py", namespaces="my.ns-test")
+    assert args == [["/src/app.py"]]
+    assert kwargs == {"namespaces": ["my.ns-test"]}
+    assert tools.lint_code(*args, **kwargs) == (("/src/app.py",), ("my.ns-test",))
+    assert rebuilt(tools.lint_code, paths="a.py")[1] == {"paths": ["a.py"]}
+
+
+def test_lists_and_other_parameters_stay_as_they_arrived():
+    tools = Tools()
+    paths = ["a.py", "b.py"]
+    args, kwargs = rebuilt(tools.lint_code, paths, cwd="/src")
+    assert args[0] is paths
+    assert kwargs == {"cwd": "/src"}
+
+
+def test_container_and_item_annotations_decide_the_shape():
+    def files(
+        paths: list[str], tags: set[str] = frozenset(), pair: tuple[str, ...] = ()
+    ):
+        return paths, tags, pair
+
+    def optional(paths: Optional[list[str]] = None, more: list[str] | None = None):  # noqa: UP045
+        return paths, more
+
+    def literal(modes: list[Literal["fast", "full"]] = ()):
+        return modes
+
+    assert rebuilt(files, "a.py", tags="x", pair="y") == (
+        [["a.py"]],
+        {"tags": {"x"}, "pair": ("y",)},
+    )
+    assert rebuilt(optional, "a.py", more="b.py") == ([["a.py"]], {"more": ["b.py"]})
+    assert rebuilt(literal, "fast") == ([["fast"]], {})
+    assert rebuilt(literal, "other") == (["other"], {})
+
+
+def test_a_member_that_takes_the_string_as_it_is_wins():
+    def either(paths: list[str] | str = (), path: str | list[str] = ""):
+        return paths, path
+
+    def anything(
+        values: list = (), items: Sequence[object] = (), raw: list[bytes] = ()
+    ):
+        return values, items, raw
+
+    assert rebuilt(either, "a.py", path="b.py") == (["a.py"], {"path": "b.py"})
+    assert rebuilt(anything, "ab", items="cd", raw="ef") == (
+        ["ab"],
+        {"items": "cd", "raw": "ef"},
+    )
+
+
+def test_path_items_take_a_bare_string_unchanged():
+    def walk(paths: list[str | Path] = ()):
+        return paths
+
+    assert rebuilt(walk, "src") == ([["src"]], {})