vis-agent 0.3.3.dev7975__tar.gz → 0.3.4.dev8033__tar.gz

{vis_agent-0.3.3.dev7975 → vis_agent-0.3.4.dev8033}/.gitignore

@@ -117,3 +117,6 @@ own_your_harness.pptx
 # Call journal written by the e2e schema-probe fixture when it runs from this
 # checkout instead of a temporary workspace.
 /schema-calls.jsonl
+
+# uv lockfiles. The SDK and the examples are libraries; uv writes the lock locally.
+uv.lock

{vis_agent-0.3.3.dev7975 → vis_agent-0.3.4.dev8033}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: vis-agent
-Version: 0.3.3.dev7975
+Version: 0.3.4.dev8033
 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.3.3.dev7975 → vis_agent-0.3.4.dev8033}/contracts/schema/agents.json

@@ -15,6 +15,9 @@
           "maxLength": 8192,
           "pattern": "\\S"
         },
+        "role": {
+          "$ref": "#/$defs/role"
+        },
         "model": {
           "type": "string",
           "minLength": 1
@@ -77,6 +80,9 @@
                   "task": {
                     "$ref": "#/$defs/spawn/properties/task"
                   },
+                  "role": {
+                    "$ref": "#/$defs/spawn/properties/role"
+                  },
                   "model": {
                     "$ref": "#/$defs/spawn/properties/model"
                   },
@@ -191,8 +197,29 @@
       ],
       "additionalProperties": false
     },
+    "answer": {
+      "$comment": "A person answers the open question of a subagent for its parent.",
+      "type": "object",
+      "properties": {
+        "session_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "text": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 8192,
+          "pattern": "\\S"
+        }
+      },
+      "required": [
+        "session_id",
+        "text"
+      ],
+      "additionalProperties": false
+    },
     "grant": {
-      "$comment": "Add file rules to the grant of a subagent. A child without write rules writes only the granted rules after a write grant.",
+      "$comment": "Add file rules to the grant of a subagent. A child without write rules already writes where its parent writes, so a write grant changes nothing for it. A write rule under a read_only or deny rule of the child fails.",
       "type": "object",
       "properties": {
         "session_id": {
@@ -238,6 +265,10 @@
         "task": {
           "$ref": "#/$defs/spawn/properties/task"
         },
+        "files": {
+          "$comment": "Replace the grant of the child for the follow-up task.",
+          "$ref": "#/$defs/files"
+        },
         "timeout_secs": {
           "$ref": "#/$defs/wait/properties/timeout_secs"
         }
@@ -270,6 +301,32 @@
       ],
       "additionalProperties": false
     },
+    "role": {
+      "description": "Choose the role by the result that you need: facts, changed files, a pass or fail, or findings.",
+      "$comment": "A role is a label for people and the leader. It sets no tool, file or model limit. The TUI writes the role name. The Companion draws a Lucide icon for each role.",
+      "oneOf": [
+        {
+          "const": "research",
+          "title": "Finds facts",
+          "description": "Finds facts. Reads code, docs, logs and history, and answers one question with evidence. Use it before you decide or plan."
+        },
+        {
+          "const": "implement",
+          "title": "Changes files",
+          "description": "Changes files. Writes code, tests, docs or configuration and runs the checks for its change. Use it for one bounded change."
+        },
+        {
+          "const": "verify",
+          "title": "Proves it works",
+          "description": "Proves that something works. Runs tests, reproduces a bug or checks the app, and reports pass or fail with evidence."
+        },
+        {
+          "const": "audit",
+          "title": "Judges the work",
+          "description": "Judges finished work. Reviews a change, plan or release for risks and mistakes, and reports findings. Give it the work, not your conclusion."
+        }
+      ]
+    },
     "model_pair": {
       "type": "object",
       "properties": {
@@ -338,6 +395,9 @@
           "type": "string",
           "minLength": 1
         },
+        "role": {
+          "$ref": "#/$defs/role"
+        },
         "status": {
           "enum": [
             "queued",
@@ -377,6 +437,42 @@
           "type": "integer",
           "minimum": 0
         },
+        "question": {
+          "type": "string",
+          "minLength": 1
+        },
+        "question_entry_id": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "budget_request": {
+          "type": "object",
+          "properties": {
+            "iterations": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "reason": {
+              "type": "string"
+            }
+          }
+        },
+        "files_request": {
+          "type": "object",
+          "properties": {
+            "files": {
+              "$ref": "#/$defs/files"
+            },
+            "reason": {
+              "type": "string"
+            }
+          }
+        },
+        "activity": {
+          "$comment": "The latest Activity line of a queued or running agent, such as Patched ~/src/a.clj.",
+          "type": "string",
+          "minLength": 1
+        },
         "usage": {
           "type": [
             "object",

{vis_agent-0.3.3.dev7975 → vis_agent-0.3.4.dev8033}/contracts/schema/config.json

@@ -694,6 +694,32 @@
       },
       "additionalProperties": false
     },
+    "toolList": {
+      "type": "array",
+      "maxItems": 256,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "pattern": "^[A-Za-z_*][A-Za-z0-9_.*]*$",
+        "maxLength": 200
+      },
+      "description": "Tool names as python_execution binds them, such as memo.recall. * matches any characters."
+    },
+    "tools": {
+      "type": "object",
+      "properties": {
+        "allow": {
+          "$ref": "#/$defs/toolList",
+          "description": "Keep only these tools of each extension that the list names. Other tools of that extension, also later ones, are off."
+        },
+        "deny": {
+          "$ref": "#/$defs/toolList",
+          "description": "Turn these tools off."
+        }
+      },
+      "additionalProperties": false,
+      "description": "Tools of optional extensions that a session can call. Every scope applies: a narrower scope can turn tools off, never on."
+    },
     "jail": {
       "type": "object",
       "properties": {
@@ -1328,6 +1354,9 @@
         "jail": {
           "$ref": "#/$defs/jail"
         },
+        "tools": {
+          "$ref": "#/$defs/tools"
+        },
         "environment": {
           "$ref": "#/$defs/environment"
         },

{vis_agent-0.3.3.dev7975 → vis_agent-0.3.4.dev8033}/contracts/schema/evals.json

@@ -580,7 +580,7 @@
       "additionalProperties": false
     },
     "agreement": {
-      "description": "The agreement of automatic results with human labels, with Cohen kappa and advice.",
+      "description": "The agreement of automatic results with human labels, with Cohen kappa, Krippendorff alpha and advice.",
       "type": "object",
       "properties": {
         "labelled": {
@@ -598,6 +598,12 @@
             "null"
           ]
         },
+        "alpha": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
         "disagreements": {
           "type": "array",
           "items": {
@@ -612,6 +618,7 @@
         "labelled",
         "agreement_percent",
         "kappa",
+        "alpha",
         "disagreements",
         "advice"
       ],

{vis_agent-0.3.3.dev7975 → vis_agent-0.3.4.dev8033}/contracts/schema/gateway.json

@@ -736,6 +736,17 @@
       },
       "path": "/v1/sessions/:sid/agents"
     },
+    {
+      "audience": "sdk",
+      "operations": {
+        "post": {
+          "request": "json",
+          "response": "json",
+          "extension": "background"
+        }
+      },
+      "path": "/v1/sessions/:sid/agents/answer"
+    },
     {
       "audience": "sdk",
       "operations": {
@@ -3000,14 +3011,27 @@
             "switch",
             "select",
             "text",
+            "secret",
             "multiline",
             "number",
             "paths",
             "filesystem",
             "network",
-            "list"
+            "list",
+            "tools"
           ]
         },
+        "is_set": {
+          "type": "boolean",
+          "description": "Whether a secret row has a saved value. A secret row never carries the value itself."
+        },
+        "suggestions": {
+          "type": "array",
+          "description": "Values that an editor offers as completions. Other values can still be valid.",
+          "items": {
+            "type": "string"
+          }
+        },
         "schema": {
           "type": "string"
         },

{vis_agent-0.3.3.dev7975 → vis_agent-0.3.4.dev8033}/contracts/schema/toggle.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://contract.blockether.com/vis/schema/toggle.json",
   "title": "Feature-toggle contract",
-  "description": "Feature-toggle contributions and the boolean tokens accepted by settings.",
+  "description": "Feature-toggle contributions, and the boolean tokens and string values that settings accept.",
   "$defs": {
     "boolean_true": {
       "type": "string",
@@ -32,6 +32,12 @@
         }
       ]
     },
+    "string_value": {
+      "type": "string",
+      "maxLength": 4096,
+      "pattern": "^[^\\u0000-\\u001f\\u007f]*$",
+      "description": "The value of a string setting: one line without control characters."
+    },
     "contribution": {
       "type": "object",
       "additionalProperties": true,
@@ -83,10 +89,15 @@
         "type": {
           "enum": [
             "boolean",
-            "enum"
+            "enum",
+            "string"
           ],
           "default": "boolean"
         },
+        "is_secret": {
+          "type": "boolean",
+          "description": "Makes a string setting write-only. Settings show only whether it is set, never its value."
+        },
         "choices": {
           "type": "array",
           "items": {},
@@ -169,6 +180,60 @@
               }
             ]
           }
+        },
+        {
+          "if": {
+            "properties": {
+              "type": {
+                "const": "string"
+              }
+            },
+            "required": [
+              "type"
+            ]
+          },
+          "then": {
+            "properties": {
+              "default": {
+                "$ref": "#/$defs/string_value"
+              }
+            },
+            "not": {
+              "required": [
+                "choices"
+              ]
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "is_secret": {
+                "const": true
+              }
+            },
+            "required": [
+              "is_secret"
+            ]
+          },
+          "then": {
+            "properties": {
+              "type": {
+                "const": "string"
+              },
+              "default": {
+                "const": ""
+              },
+              "scopes": {
+                "const": [
+                  "global"
+                ]
+              }
+            },
+            "required": [
+              "type"
+            ]
+          }
         }
       ]
     },

{vis_agent-0.3.3.dev7975 → vis_agent-0.3.4.dev8033}/pyproject.toml

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

vis_agent-0.3.4.dev8033/release-tag

@@ -0,0 +1 @@
+beta-8906d28bc9e78c61bfe556c52e15d3045f046731

{vis_agent-0.3.3.dev7975 → vis_agent-0.3.4.dev8033}/src/blockether/vis/engine/__init__.py

@@ -4,7 +4,7 @@ For installation, workflows and lifecycle choices, use the
 [Python SDK guide](https://vis.blockether.com/python-sdk.html).
 """
 
-from ._agent import Agent, StructuredOutputError
+from ._agent import Agent, StructuredOutputError, final_answer
 from ._agents import Subagent, SubagentRecord
 from ._client import (
     Event,
@@ -70,5 +70,6 @@ __all__ = [
     "Turn",
     "VisTimeout",
     "ensure_installed",
+    "final_answer",
     "install",
 ]

{vis_agent-0.3.3.dev7975 → vis_agent-0.3.4.dev8033}/src/blockether/vis/engine/_agent.py

@@ -239,7 +239,13 @@ def _syntax_message(answer: str, error: json.JSONDecodeError) -> str:
     return f"not valid JSON: {error.msg} at {where}"
 
 
-def _final_answer(turn: dict) -> str | None:
+def final_answer(turn: dict) -> str | None:
+    """Return the final answer text of the turn record `turn`, or None.
+
+    A turn record has no `answer` field. The answer is the Markdown of the last
+    `prose` block in `turn["content"]`. A turn without that block, or with only
+    blank text in it, gives None.
+    """
     content = turn.get("content")
     if not isinstance(content, list):
         return None
@@ -397,7 +403,7 @@ def _run(
                 {"turn": turn, "answer": None, "errors": [_turn_problem(turn)]}
             )
             raise StructuredOutputError(f"{name} turn did not complete", attempts)
-        answer = _final_answer(turn)
+        answer = final_answer(turn)
         result, problems = contract.validate(answer)
         if not problems:
             return result

{vis_agent-0.3.3.dev7975 → vis_agent-0.3.4.dev8033}/src/blockether/vis/engine/_agents.py

@@ -18,10 +18,16 @@ class Subagent:
     status: str
     iteration_budget: int
     iterations_used: int
+    role: str | None = None
     provider: str | None = None
     model: str | None = None
     routing_locked: bool = False
     pending_input: bool = False
+    question: str | None = None
+    question_entry_id: int | None = None
+    budget_request: dict[str, Any] | None = None
+    files_request: dict[str, Any] | None = None
+    activity: str | None = None
     usage: dict[str, Any] | None = None
     files: dict[str, list[str]] | None = None
 

{vis_agent-0.3.3.dev7975 → vis_agent-0.3.4.dev8033}/src/blockether/vis/engine/_council.py

@@ -231,6 +231,7 @@ class Council:
         self,
         task: str,
         *,
+        role: str | None = None,
         provider: str | None = None,
         model: str | None = None,
         iteration_budget: int | None = None,
@@ -247,12 +248,15 @@ class Council:
         it with different input is rejected. This is not an ordinary independent fork,
         and it does not grant broader permissions. ``files`` narrows file access with
         ``write``, ``read_only`` and ``deny`` rules: paths or globs, also for future files.
+        ``role`` is ``research``, ``implement``, ``verify`` or ``audit``: a label for people
+        that sets no limit.
         """
         body = {"task": task}
         body.update(
             {
                 name: value
                 for name, value in {
+                    "role": role,
                     "provider": provider,
                     "iteration_budget": iteration_budget,
                     "model": model,
@@ -291,8 +295,8 @@ class Council:
     ) -> tuple[SubagentRecord, ...]:
         """Spawn one subagent for each task, wait for all of them and return their records.
 
-        A task is a string, or a dict with ``task`` and optional ``model``, ``provider``,
-        ``iteration_budget`` and ``files``. The wait ends when every child answers, asks
+        A task is a string, or a dict with ``task`` and optional ``role``, ``model``,
+        ``provider``, ``iteration_budget`` and ``files``. The wait ends when every child answers, asks
         or stops, or after ``timeout_secs`` (at most 1800). A running child stays running.
         """
         body = {"tasks": tasks, "timeout_secs": timeout_secs}
@@ -316,15 +320,27 @@ class Council:
         return self._records("/cancel", {"session_id": session_id}, "cancel")[0]
 
     def resume(
-        self, session_id: str, task: str, *, timeout_secs: int = 240
+        self,
+        session_id: str,
+        task: str,
+        *,
+        files: dict[str, list[str]] | None = None,
+        timeout_secs: int = 240,
     ) -> SubagentRecord:
         """Give a finished subagent a follow-up task in its own session, then wait for it.
 
         The parent must be active, as for ``spawn``: an idle parent gets
         ``inactive-session``. The child keeps its whole context. A child without
         iterations left needs ``extend`` first. A running child needs ``wait``.
+        ``files`` replaces the file grant of the child for the follow-up task.
         """
-        body = {"session_id": session_id, "task": task, "timeout_secs": timeout_secs}
+        body: dict[str, Any] = {
+            "session_id": session_id,
+            "task": task,
+            "timeout_secs": timeout_secs,
+        }
+        if files is not None:
+            body["files"] = files
         return self._records("/resume", body, "resume", timeout_secs)[0]
 
     def extend(self, session_id: str, iterations: int) -> SubagentRecord:
@@ -340,11 +356,19 @@ class Council:
         body = {"session_id": session_id, "reason": reason}
         return self._records("/deny", body, "deny")[0]
 
+    def answer(self, session_id: str, text: str) -> SubagentRecord:
+        """Answer the open question of a subagent for its parent; the child continues."""
+        body = {"session_id": session_id, "text": text}
+        return self._records("/answer", body, "answer")[0]
+
     def grant(self, session_id: str, files: dict[str, list[str]]) -> SubagentRecord:
         """Add ``write``, ``read_only`` or ``deny`` file rules to the grant of a subagent.
 
-        A grant gives at most your own access. The record has a ``warning`` when an
-        active sibling can write the same files.
+        A grant gives at most your own access. A write rule that the child can already
+        write changes nothing. A write rule under a ``read_only`` or ``deny`` rule of the
+        child fails: use ``resume`` with ``files`` for a new scope. The record has a
+        ``warning`` for unchanged write rules and for an active sibling that can write
+        the same files.
         """
         body = {"session_id": session_id, "files": files}
         return self._records("/grant", body, "grant")[0]