vis-agent 0.1.43__py3-none-any.whl

blockether/vis/__init__.py

@@ -0,0 +1,6 @@
+"""Vis SDK: extension authoring and explicit engine clients.
+
+Import ``blockether.vis.extension`` to author an extension, or
+``blockether.vis.engine`` to control an engine. Importing this package performs
+no host initialization, registration, process startup or gateway connection.
+"""

blockether/vis/_contracts.py

@@ -0,0 +1,142 @@
+"""Private reader and validator for the canonical, language-neutral Vis documents."""
+
+import json
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+_DATA = Path(__file__).with_name("_data")
+if not _DATA.is_dir():
+    _DATA = Path(__file__).resolve().parents[4] / "vis-contract/resources/vis-contract"
+
+
+def _load_document(name):
+    return json.loads((_DATA / f"{name}.json").read_text(encoding="utf-8"))
+
+
+_DOCUMENT_NAMES = (
+    "activity",
+    "gateway",
+    "view",
+    "content",
+    "config",
+    "toggle",
+    "provider",
+    "surface",
+    "test-runner",
+)
+_SCHEMA_NAMES = (*_DOCUMENT_NAMES, "python-host", "common")
+
+_host = _load_document("python-host")
+CONTRACT = {
+    "version": _host["version"],
+    "ops": _host["ops"],
+    "shell": _host["shell"],
+    "live": _host["live"],
+    **{name.replace("-", "_"): _load_document(name) for name in _DOCUMENT_NAMES},
+}
+"""All canonical contract documents, keyed as the public Python API expects."""
+
+ACTIVITY = CONTRACT["activity"]
+"""Host-owned tool lifecycle evidence, closed vocabulary, and presentation limits."""
+
+GATEWAY = CONTRACT["gateway"]
+"""Canonical routes, headers, events, envelopes and replay semantics."""
+
+VERSION = CONTRACT["version"]
+"""Bumped whenever an op is added, removed or re-shaped."""
+
+OPS = {entry["name"]: entry for entry in CONTRACT["ops"]}
+"""Every declared op by name, in document order."""
+
+SHELL = CONTRACT["shell"]
+"""The `shell` verb's lifecycle grammar: `default_op`, `handle_ops`, `spawn_ops`."""
+
+LIVE = CONTRACT["live"]
+"""The `live` operation vocabulary and flush interval."""
+
+VIEW = CONTRACT["view"]
+"""The closed View vocabulary — lifecycle kinds, semantic nodes and their bounds."""
+
+CONTENT = CONTRACT["content"]
+"""Canonical content vocabulary."""
+
+CONFIG = CONTRACT["config"]
+"""Canonical configuration vocabulary."""
+
+TOGGLE = CONTRACT["toggle"]
+"""Canonical toggle vocabulary."""
+
+PROVIDER = CONTRACT["provider"]
+"""Canonical provider-limits vocabulary."""
+
+SURFACE = CONTRACT["surface"]
+"""Canonical language-surface vocabulary."""
+
+TEST_RUNNER = CONTRACT["test_runner"]
+"""Canonical test-runner vocabulary."""
+
+
+def schema(name: str) -> dict[str, Any]:
+    """Read the shipped JSON Schema; never retrieve schemas from the network."""
+    if name not in _SCHEMA_NAMES:
+        raise ValueError("unknown contract document")
+    return _load_document("schema/" + name)
+
+
+@lru_cache(maxsize=64)
+def _validator(name: str, definition: str):
+    from jsonschema import Draft202012Validator, FormatChecker
+    from referencing import Registry, Resource
+
+    source = schema(name)
+    if definition not in source.get("$defs", {}):
+        raise ValueError("unknown contract definition")
+    registry = Registry().with_resources(
+        (document["$id"], Resource.from_contents(document))
+        for document in (schema(name) for name in _SCHEMA_NAMES)
+    )
+    target = {key: source[key] for key in ("$schema", "$id", "$defs")}
+    target["$ref"] = "#/$defs/" + definition
+    return Draft202012Validator(
+        target, registry=registry, format_checker=FormatChecker()
+    )
+
+
+def _json_value(item):
+    import math
+
+    if item is None or type(item) in (str, bool, int):
+        return True
+    if type(item) is float:
+        return math.isfinite(item)
+    if type(item) is list:
+        return all(_json_value(child) for child in item)
+    return type(item) is dict and all(
+        type(k) is str and _json_value(v) for k, v in item.items()
+    )
+
+
+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
+    authorization belong to the engine, not JSON Schema.
+    """
+    try:
+        valid = _json_value(value) and _validator(name, definition).is_valid(value)
+    except (RecursionError, TypeError, ValueError):
+        valid = False
+    if not valid:
+        raise ValueError(f"invalid {name}.{definition} contract")
+    return value
+
+
+def op(name):
+    """The declared op called `name`, or None."""
+    return OPS.get(name)
+
+
+def refusal(name):
+    """The refusal message for an op unavailable outside Vis, if any."""
+    return OPS.get(name, {}).get("refusal")

blockether/vis/_data/activity.json

@@ -0,0 +1,50 @@
+{
+  "version": 1,
+  "event": "block.activity",
+  "presenters": [
+    "generic",
+    "shell",
+    "tests",
+    "patch",
+    "observation",
+    "lint",
+    "repl",
+    "format",
+    "list"
+  ],
+  "signals": [
+    "generic",
+    "observation",
+    "mutation",
+    "verification"
+  ],
+  "states": [
+    "idle",
+    "running",
+    "succeeded",
+    "failed",
+    "cancelled"
+  ],
+  "text_formats": [
+    "inline",
+    "markdown"
+  ],
+  "limits": {
+    "max_rows": 128,
+    "max_depth": 2,
+    "max_resources": 8,
+    "max_receipt_bytes": 65536,
+    "max_summary_bytes": 512,
+    "max_detail_bytes": 2048,
+    "max_event_bytes": 262144,
+    "max_diff_line_bytes": 512
+  },
+  "semantics": {
+    "ownership": "A projection belongs to its containing form. Only the event envelope carries session, turn, iteration and form_index. Activity is not a View and never enters model context.",
+    "delivery": "Each block.activity is a complete replacement, not a delta. Envelope seq orders revisions. Reconnect replays the latest replacement; settled evidence is durable.",
+    "lifecycle": "The engine allocates invocation identity and entry sequence, records running before execution, and exactly one succeeded, failed or cancelled result. Presentation cannot control the operation.",
+    "counts": "Counts describe observed invocations, including omitted rows. Group rows are presentation, not additional invocations. omitted.by_classification counts omitted evidence by signal.",
+    "bounds": "Redact credential-bearing structured fields before summarizing; enforce UTF-8 byte limits. Row ids are globally unique within a projection. At most max_rows top-level rows and max_depth child edges. Omission is explicit, never invented success.",
+    "declaration": "Symbols publish a presentation: headline, one-line summary, content blocks and optional sections of the same headline/summary/content shape. Headline and summary remain visible when collapsed; only content is disclosed. Up to 8 sections, 32 blocks in total and 32 KiB per replacement; each headline and summary is at most 512 UTF-8 bytes. Content includes headings, Markdown, tables, code, diffs, attachment references and progress. The engine alone owns identity, timing and outcome; presentation failures never alter tool results."
+  }
+}

blockether/vis/_data/config.json

@@ -0,0 +1,64 @@
+{
+  "api_style_values": [
+    "anthropic",
+    "openai",
+    "openai-responses",
+    "gemini"
+  ],
+  "api_style_aliases": {
+    "anthropic": "anthropic",
+    "anthropic-messages": "anthropic",
+    "anthropic_messages": "anthropic",
+    "claude": "anthropic",
+    "messages": "anthropic",
+    "openai": "openai-compatible-chat",
+    "openai-chat": "openai-compatible-chat",
+    "openai_chat": "openai-compatible-chat",
+    "openai-compatible": "openai-compatible-chat",
+    "openai_compatible": "openai-compatible-chat",
+    "openai-compatible-chat": "openai-compatible-chat",
+    "openai_compatible_chat": "openai-compatible-chat",
+    "chat": "openai-compatible-chat",
+    "chat-completions": "openai-compatible-chat",
+    "chat_completions": "openai-compatible-chat",
+    "openai-responses": "openai-compatible-responses",
+    "openai_responses": "openai-compatible-responses",
+    "openai-compatible-responses": "openai-compatible-responses",
+    "openai_compatible_responses": "openai-compatible-responses",
+    "responses": "openai-compatible-responses",
+    "gemini": "gemini",
+    "google": "gemini",
+    "google-gemini": "gemini",
+    "google_gemini": "gemini"
+  },
+  "workspace_access_values": [
+    "read-only",
+    "readonly",
+    "ro",
+    "read-write",
+    "readwrite",
+    "rw"
+  ],
+  "workspace_draft_values": [
+    "shared",
+    "copy-only",
+    "copy-and-apply",
+    "not-allowed"
+  ],
+  "workspace_os_values": [
+    "macos",
+    "linux",
+    "wsl",
+    "windows"
+  ],
+  "jail_environment_values": [
+    "declared",
+    "inherit"
+  ],
+  "titling_modes": [
+    "llm",
+    "first_sentence",
+    "first_words",
+    "disabled"
+  ]
+}

blockether/vis/_data/content.json

@@ -0,0 +1,50 @@
+{
+  "block_types": [
+    "attachment",
+    "code",
+    "error",
+    "notice",
+    "prose",
+    "reasoning",
+    "speech",
+    "tool"
+  ],
+  "delta_fields": [
+    "markdown",
+    "text"
+  ],
+  "event_types": [
+    "content.block.completed",
+    "content.block.delta",
+    "content.block.started",
+    "turn.cancelled",
+    "turn.completed",
+    "turn.failed"
+  ],
+  "message_statuses": [
+    "cancelled",
+    "completed",
+    "failed",
+    "streaming",
+    "suspended"
+  ],
+  "reasoning_visibilities": [
+    "private",
+    "visible"
+  ],
+  "roles": [
+    "assistant",
+    "developer",
+    "system",
+    "tool",
+    "user"
+  ],
+  "tool_statuses": [
+    "cancelled",
+    "completed",
+    "failed",
+    "pending",
+    "running"
+  ],
+  "version": 2
+}