agentengine-sdk-python 0.8.5__py3-none-any.whl → 0.8.6__py3-none-any.whl

ksadk/harness/native/artifact_search_capacity.py

@@ -0,0 +1,206 @@
+"""Pure quote for complete next requests after a canonical Search group.
+
+No summaries, old receipts or source bytes are changed. Synthetic result shapes
+exist only in a detached reducer projection, never as Run facts. The estimate
+covers ordinary completion without intervening commands or host changes.
+"""
+
+import json
+from dataclasses import dataclass
+
+from .artifact_search_contract import ARTIFACT_SEARCH_DEFINITION
+from .context_runtime_contracts import CompactionHistory
+from .delivery_review import delivery_review_messages
+from .effective_configuration import effective_run_configuration
+from .machine import next_transition, reduce_parallel_readonly_tools, reduce_tool
+from .model import ModelToolCall
+from .ports import ToolResult, digest
+from .state import RunPhase
+from .tool_budget import model_instructions, model_tool_surface, model_turn_control
+from .transitions import commit_transition
+
+SEARCH_CAPACITY_POLICY = "complete-next-search-request/v1"
+
+
+@dataclass(frozen=True)
+class SearchGroupCapacity:
+    result_message_units: int
+    group_size: int
+    pending_count: int
+    maximum_fixed_and_history_units: int
+
+
+def _declared_group(snapshot):
+    index = next(
+        (
+            i
+            for i in range(len(snapshot.messages) - 1, -1, -1)
+            if snapshot.messages[i].get("role") == "assistant"
+            and snapshot.messages[i].get("tool_calls")
+        ),
+        None,
+    )
+    if index is None:
+        return None
+    declared, tail = snapshot.messages[index], snapshot.messages[index + 1 :]
+    try:
+        calls = declared["tool_calls"]
+        if (
+            not calls
+            or len({c["id"] for c in calls}) != len(calls)
+            or len(tail) + len(snapshot.pending_tools) != len(calls)
+            or any(c["function"]["name"] != "ArtifactSearch" for c in calls)
+        ):
+            return None
+        arguments = [json.loads(c["function"]["arguments"]) for c in calls]
+        if len({json.dumps(a, sort_keys=True) for a in arguments}) != len(calls):
+            return None
+        if any(
+            m.get("role") != "tool"
+            or m.get("tool_call_id") != c["id"]
+            or m.get("receipt_goal_revision") != snapshot.goal_revision
+            or json.loads(m["content"]).get("status") != "ok"
+            for m, c in zip(tail, calls)
+        ):
+            return None
+        expected = tuple(
+            ModelToolCall(call_id=c["id"], name="ArtifactSearch", arguments=a).model_dump(
+                mode="json"
+            )
+            for c, a in zip(calls[len(tail) :], arguments[len(tail) :])
+        )
+        if expected != snapshot.pending_tools:
+            return None
+        if len(calls) == 1:
+            previous = next(
+                (
+                    m
+                    for m in reversed(snapshot.messages[:index])
+                    if m.get("role") == "assistant" and m.get("tool_calls")
+                ),
+                None,
+            )
+            if previous:
+                prior = previous["tool_calls"][-1]["function"]
+                if (
+                    prior["name"] == "ArtifactSearch"
+                    and json.loads(prior["arguments"]) == arguments[0]
+                ):
+                    return None
+    except (KeyError, TypeError, ValueError):
+        return None
+    return declared, tail
+
+
+def search_group_capacity(snapshot, configuration, driver):
+    if (
+        snapshot.configuration_digest != configuration.digest
+        or snapshot.profile_digest != digest(configuration.profile)
+        or snapshot.context_binding != driver.binding
+    ):
+        raise ValueError("search_configuration_mismatch")
+    planner = driver.planner
+    if (
+        planner is None
+        or snapshot.phase != RunPhase.EXECUTING_TOOLS
+        or not snapshot.pending_tools
+        or not snapshot.pending_intent
+        or snapshot.force_compaction
+    ):
+        return None
+    group = _declared_group(snapshot)
+    if group is None:
+        return None
+    declared, sealed = group
+    config = effective_run_configuration(configuration, snapshot)
+    installed = [t for t in config.tools if t.name == "ArtifactSearch"]
+    if (
+        len(installed) != 1
+        or installed[0].model_copy(update={"feedback_profile_digest": None})
+        != ARTIFACT_SEARCH_DEFINITION.model_copy(update={"feedback_profile_digest": None})
+        or snapshot.tool_calls + snapshot.descendant_tool_calls + len(snapshot.pending_tools)
+        > config.limits.max_tool_calls
+        or snapshot.pending_intent != f"{snapshot.run_id}:effect:{snapshot.revision}"
+    ):
+        return None
+    current, first = snapshot.model_copy(deep=True), True
+    pending_ids = {c["call_id"] for c in snapshot.pending_tools}
+    while current.pending_tools:
+        before = (
+            current.model_copy(update={"revision": current.revision - 1, "pending_intent": None})
+            if first
+            else current
+        )
+        transition = next_transition(before, config)
+        if (
+            transition is None
+            or not transition.intents
+            or transition.intents[0].kind != "tool"
+        ):
+            return None
+        intent = transition.intents[0]
+        if first and intent.operation_key != current.pending_intent:
+            return None
+        current = transition.snapshot
+        calls = intent.payload.get("calls") or [intent.payload["call"]]
+        if len(calls) > 1:
+            updated = reduce_parallel_readonly_tools(
+                current,
+                ToolResult(status="ok", content={
+                    "batch_results": [ToolResult(status="ok", content="").model_dump(
+                        mode="json"
+                    ) for _ in calls],
+                }),
+                calls,
+                definitions=config.tools,
+            )
+        else:
+            updated = reduce_tool(
+                current,
+                ToolResult(status="ok", content=""),
+                definition=installed[0],
+            )
+        current = commit_transition(current, updated, "effect.received").snapshot
+        first = False
+    transition = next_transition(current, config)
+    if transition is None or transition.snapshot.phase != RunPhase.PREPARING_CONTEXT:
+        return None
+    current = transition.snapshot
+    history = CompactionHistory.model_validate(current.compaction_history)
+    remaining, costs = len(pending_ids), []
+    for progress in range(
+        snapshot.observed_progress_revision, snapshot.observed_progress_revision + remaining + 1
+    ):
+        projected = current.model_copy(update={"observed_progress_revision": progress})
+        plan = planner.plan(
+            source_revision=projected.revision,
+            model_turn=projected.model_calls,
+            profile=config.profile,
+            instructions=model_instructions(projected, config),
+            tools=model_tool_surface(projected, config),
+            context_tools=config.tools,
+            messages=delivery_review_messages(projected),
+            continuity=driver.continuity(projected, config),
+            contract=config.contract,
+            history=history,
+            force_compaction=False,
+            turn_control=model_turn_control(projected, config),
+            allow_compaction=False,
+        )
+        if plan.action != "ready" or plan.prepared is None:
+            return None
+        synthetic = [
+            m
+            for m in plan.prepared.messages
+            if m.get("role") == "tool" and m.get("tool_call_id") in pending_ids
+        ]
+        if len(synthetic) != remaining:
+            return None
+        costs.append(
+            plan.prepared.counted_input_tokens
+            - sum(planner.count_model_message(m, config.profile) for m in synthetic)
+        )
+    available = config.profile.context_window - config.profile.max_output_tokens - max(costs)
+    sealed_cost = sum(planner.count_model_message(m, config.profile) for m in sealed)
+    units = min(available // remaining, (available + sealed_cost) // len(declared["tool_calls"]))
+    return SearchGroupCapacity(units, len(declared["tool_calls"]), remaining, max(costs))

ksadk/harness/native/artifact_search_contract.py

@@ -0,0 +1,40 @@
+"""Canonical reserved artifact search contract; no effect owner dependencies."""
+
+import hashlib
+
+from .ports import ToolDefinition
+
+ARTIFACT_SEARCH_NAME = "ArtifactSearch"
+ARTIFACT_SEARCH_DEFINITION = ToolDefinition(
+    name=ARTIFACT_SEARCH_NAME,
+    description=(
+        "Search saved complete observations using a literal query and previously returned artifact "
+        "URIs. Captured workspace source retains its original path and line numbers. "
+        "The query is literal, case-sensitive, and never a shell command or regular expression. "
+        "Matches are non-overlapping. complete=false indicates omissions; "
+        "inspect that flag before claiming no matches."
+    ),
+    parameters={
+        "type": "object",
+        "additionalProperties": False,
+        "required": ["uris", "query"],
+        "properties": {
+            "uris": {
+                "type": "array",
+                "minItems": 1,
+                "maxItems": 8,
+                "uniqueItems": True,
+                "items": {"type": "string", "minLength": 1},
+            },
+            "query": {"type": "string", "minLength": 1, "maxLength": 1024},
+            "max_matches": {"type": "integer", "minimum": 1, "maximum": 16},
+            "context_chars": {"type": "integer", "minimum": 0, "maximum": 256},
+        },
+    },
+    read_only=True,
+    concurrent_safe=True,
+    progress_observation=True,
+    context_role="workspace_search",
+    feedback_profile_digest="sha256:"
+    + hashlib.sha256(b"artifact-search-public-argument-feedback/v1").hexdigest(),
+)

ksadk/harness/native/artifact_single_read_capacity.py

@@ -0,0 +1,170 @@
+"""Pure admission of one complete ArtifactRead through the real planner.
+
+A page may be fully quoted in one bounded summary instead of retained beside
+it. These detached projections never become receipts or dispatch any effects.
+"""
+
+from __future__ import annotations
+
+import json
+
+from .artifact_partial_read_capacity import _valid_arguments
+from .artifact_read_capacity import _declared_group
+from .artifact_read_contract import ARTIFACT_READ_DEFINITION
+from .context_artifact_page import artifact_page_observation
+from .context_fresh_tools import FRESH_TOOL_OBSERVATION_POLICY, fresh_tool_group_refs
+from .context_partition import source_manifest
+from .context_runtime import CompactionController, CompactionHistory
+from .delivery_review import review_pending
+from .effective_configuration import effective_run_configuration
+from .machine import next_transition, reduce_tool
+from .ports import ToolResult, digest
+from .state import RunPhase
+from .tool_budget import (
+    finalization_only,
+    model_instructions,
+    model_tool_surface,
+    model_turn_control,
+)
+from .transitions import commit_transition
+
+SINGLE_ARTIFACT_CAPACITY_POLICY = "single-read-complete-planner-admission/v1"
+
+
+def single_artifact_group_admission(snapshot, configuration, driver):
+    """Quote one original read, without guessing other results or commands."""
+    if (
+        snapshot.configuration_digest != configuration.digest
+        or snapshot.profile_digest != digest(configuration.profile)
+        or snapshot.context_binding != driver.binding
+    ):
+        raise ValueError("source_read_configuration_mismatch")
+    planner = driver.planner
+    if (
+        planner is None
+        or snapshot.phase != RunPhase.EXECUTING_TOOLS
+        or snapshot.force_compaction
+        or review_pending(snapshot)
+        or len(snapshot.pending_tools) != 1
+        or snapshot.pending_intent != f"{snapshot.run_id}:effect:{snapshot.revision}"
+        or snapshot.revision < 1
+        or snapshot.event_seq < 1
+    ):
+        return None
+    group = _declared_group(snapshot)
+    if group is None or len(group[0]["tool_calls"]) != 1 or group[1]:
+        return None
+    call = snapshot.pending_tools[0]
+    if not _valid_arguments(call["arguments"]):
+        return None
+    config = effective_run_configuration(configuration, snapshot)
+    installed = [t for t in config.tools if t.name == ARTIFACT_READ_DEFINITION.name]
+    remaining_models = config.limits.max_model_calls - (
+        snapshot.model_calls + snapshot.descendant_model_calls
+    )
+    if (
+        len(installed) != 1
+        or installed[0].model_copy(update={"feedback_profile_digest": None})
+        != ARTIFACT_READ_DEFINITION
+        or snapshot.tool_calls + snapshot.descendant_tool_calls >= config.limits.max_tool_calls
+        or remaining_models < 1
+    ):
+        return None
+    current = snapshot.model_copy(deep=True)
+    prepared = next_transition(current.model_copy(update={
+        "revision": current.revision - 1,
+        "event_seq": current.event_seq - 1,
+        "pending_intent": None,
+    }), config)
+    if (
+        prepared is None or len(prepared.intents) != 1
+        or prepared.intents[0].kind != "tool"
+        or prepared.intents[0].operation_key != current.pending_intent
+        or prepared.intents[0].payload != {"call": call}
+        or prepared.snapshot != current
+    ):
+        return None
+    ref = next((r for r in current.artifact_refs if r["uri"] == call["arguments"]["uri"]), None)
+    if ref is None:
+        return None
+
+    def admit(result):
+        if (
+            not isinstance(result, ToolResult) or result.status != "ok"
+            or result != ToolResult(status="ok", content=result.content)
+            or not isinstance(result.content, dict)
+            or any(result.content.get(k) != v for k, v in ref.items())
+            or not (result.content.get("content") or result.content.get("complete") is True)
+        ):
+            return False
+        message = {"role": "tool", "tool_call_id": call["call_id"],
+                   "content": json.dumps({"status": "ok", "content": result.content},
+                                         ensure_ascii=False)}
+        if artifact_page_observation(message, arguments=call["arguments"]) is None:
+            return False
+        received = commit_transition(
+            current, reduce_tool(current, result, definition=installed[0]), "effect.received",
+        )
+        completed = next_transition(received.snapshot, config)
+        if (
+            completed is None or completed.intents
+            or completed.snapshot.phase != RunPhase.PREPARING_CONTEXT
+            or completed.snapshot.pending_tools
+            or completed.snapshot.messages[:len(current.messages)] != current.messages
+            or len(completed.snapshot.messages) != len(current.messages) + 1
+            or completed.snapshot.tool_calls != current.tool_calls + 1
+            or completed.snapshot.model_calls != current.model_calls
+            or completed.snapshot.compaction_history != current.compaction_history
+        ):
+            return False
+        projected = completed.snapshot
+        continuity = driver.continuity(projected, config)
+        plan = planner.plan(
+            source_revision=projected.revision, model_turn=projected.model_calls,
+            profile=config.profile, instructions=model_instructions(projected, config),
+            tools=model_tool_surface(projected, config), context_tools=config.tools,
+            messages=projected.messages, continuity=continuity, contract=config.contract,
+            history=CompactionHistory.model_validate(projected.compaction_history),
+            force_compaction=False, turn_control=model_turn_control(projected, config),
+            allow_compaction=not finalization_only(projected, config),
+        )
+        if plan.action == "ready":
+            return bool(plan.prepared and plan.prepared.counted_input_tokens
+                        + config.profile.max_output_tokens <= config.profile.context_window)
+        if plan.action != "compact" or remaining_models < 2:
+            return False
+        request = plan.request
+        if (
+            request is None or request.remaining_history_entries
+            or request.summary_output_tokens != config.profile.max_output_tokens
+            or request.fresh_tool_observation_policy != FRESH_TOOL_OBSERVATION_POLICY
+            or frozenset(request.fresh_tool_message_refs)
+            != fresh_tool_group_refs(projected.messages)
+            or request.summary_partition is None or request.summary_partition.pending is None
+            or request.summary_partition.pending_source_parts
+        ):
+            return False
+        # Require complete coverage in this request, not a promise that later
+        # unknown summary chunks will fit. The real seal still checks output.
+        CompactionController(planner)._validate_source(
+            request, projected.revision, continuity, projected.messages,
+        )
+        manifest, _ = source_manifest(
+            projected.messages, request.old_messages, request.retained_message_refs,
+            capture_reader_names=request.source_capture_reader_names,
+            fresh_tool_observation_policy=request.fresh_tool_observation_policy,
+            fresh_tool_message_refs=request.fresh_tool_message_refs,
+            fresh_text_fragment_policy=request.fresh_text_fragment_policy,
+            fresh_text_excluded_tool_names=request.source_reader_names,
+        )
+        return bool(
+            request.summary_partition.pending.stop == len(manifest["dropped"])
+            and request.summary_counted_input_tokens + request.summary_output_tokens
+            <= config.profile.context_window
+            and sum(planner.count_model_message(m, config.profile)
+                    for m in request.retained_messages)
+            + planner.summary_reservation(config.profile)
+            <= request.budget.input_capacity
+        )
+
+    return admit

ksadk/harness/native/browser_contract.py

@@ -0,0 +1,229 @@
+"""Serializable browser evidence. A successful action is never an acceptance verdict."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Literal
+
+from pydantic import Field, JsonValue, ValidationInfo, field_validator, model_validator
+
+from .state import Contract, RunScope
+
+
+class BrowserSessionError(RuntimeError):
+    """A stable error code, without page contents, credentials or driver diagnostics."""
+
+
+class BrowserSessionRef(Contract):
+    schema_version: Literal["ksadk.browser-session/v1"] = "ksadk.browser-session/v1"
+    session_id: str = Field(min_length=1)
+    scope: RunScope
+    run_id: str = Field(min_length=1)
+    runtime_id: str = Field(min_length=1)
+    backend: Literal["playwright"] = "playwright"
+    workspace_revision: str = Field(min_length=1)
+    generation: int = Field(default=1, ge=1)
+    lease_epoch: int = Field(default=1, ge=1)
+
+
+class BrowserAction(Contract):
+    action_id: str = Field(min_length=1, max_length=256)
+    kind: Literal["navigate", "click", "fill", "press", "move", "scroll", "screenshot", "close"]
+    url: str | None = Field(default=None, max_length=8192)
+    selector: str | None = Field(default=None, max_length=2048)
+    element_ref: str | None = Field(default=None, min_length=1, max_length=64)
+    value: str | None = Field(default=None, max_length=65536)
+    key: str | None = Field(default=None, max_length=128)
+    button: Literal["left", "right", "middle"] | None = None
+    x: int | None = Field(default=None, strict=True, ge=0, le=4096)
+    y: int | None = Field(default=None, strict=True, ge=0, le=4096)
+    steps: int | None = Field(default=None, strict=True, ge=1, le=30)
+    delta_x: int | None = Field(default=None, strict=True, ge=-10000, le=10000)
+    delta_y: int | None = Field(default=None, strict=True, ge=-10000, le=10000)
+    # Bounded key/mouse hold duration for real-time interactions. The driver
+    # releases the input within one action rather than persisting a held key.
+    duration_ms: int | None = Field(default=None, strict=True, ge=0, le=5000)
+    # Allow a bounded input dispatch plus two read-only observation attempts
+    # under the action deadline. A shorter caller-pinned limit still wins.
+    timeout_ms: int = Field(default=30000, ge=1, le=120000)
+
+    @field_validator("value", "key", mode="before")
+    @classmethod
+    def normalize_numeric_text_input(cls, value: object, info: ValidationInfo) -> object:
+        # HTML fill and keyboard digit presses are text operations. Some model
+        # transports encode a digit-only argument as a JSON integer, so admit
+        # that value explicitly at this boundary while preserving every other
+        # argument's strict schema.
+        if type(value) is int:
+            if info.field_name == "value":
+                return str(value)
+            if 0 <= value <= 9:
+                return str(value)
+        return value
+
+    @model_validator(mode="after")
+    def valid_arguments(self) -> BrowserAction:
+        if self.kind in {"click", "fill", "press"}:
+            if (self.selector is None) == (self.element_ref is None):
+                raise ValueError("browser action requires one target")
+        required = {
+            "navigate": {"url"},
+            "click": {"selector"},
+            "fill": {"selector", "value"},
+            "press": {"selector", "key"},
+            "move": {"x", "y"},
+            "scroll": {"delta_x", "delta_y"},
+            "screenshot": set(),
+            "close": set(),
+        }[self.kind]
+        if self.element_ref is not None and self.kind in {"click", "fill", "press"}:
+            required = (required - {"selector"}) | {"element_ref"}
+        supplied = {
+            name
+            for name in (
+                "url",
+                "selector",
+                "element_ref",
+                "value",
+                "key",
+                "button",
+                "x",
+                "y",
+                "steps",
+                "delta_x",
+                "delta_y",
+                "duration_ms",
+            )
+            if getattr(self, name) is not None
+        }
+        if self.kind in {"click", "press"}:
+            supplied.discard("duration_ms")
+        if self.kind == "click":
+            supplied.discard("button")
+        if self.kind == "move":
+            supplied.discard("steps")
+        if self.kind == "scroll":
+            if (self.x is None) != (self.y is None):
+                raise ValueError("scroll anchor requires both coordinates")
+            supplied.difference_update({"x", "y"})
+        if supplied != required or any(
+            not getattr(self, name)
+            for name in required - {"value", "x", "y", "delta_x", "delta_y"}
+        ):
+            raise ValueError("invalid browser action arguments")
+        return self
+
+
+class BrowserImage(Contract):
+    content_ref: str = Field(min_length=1)
+    mime_type: Literal["image/png"] = "image/png"
+    width: int = Field(gt=0)
+    height: int = Field(gt=0)
+    # The host adapter creates this block from screenshot bytes. Tool text and
+    # arbitrary filesystem paths must never be promoted into trusted image data.
+    content_block: dict[str, JsonValue]
+
+
+class BrowserControl(Contract):
+    """Bounded, untrusted DOM hint; never includes an input's current value."""
+
+    tag: str = Field(min_length=1, max_length=32)
+    role: str = Field(default="", max_length=80)
+    label: str = Field(default="", max_length=160)
+    selector: str | None = Field(default=None, min_length=1, max_length=512)
+    # Opaque host reference to this DOM node; not a page-supplied selector.
+    element_ref: str | None = Field(default=None, min_length=1, max_length=64)
+    clickable: bool = False
+    # Current-viewport pointer hit test, not proof that a click will succeed.
+    # None means the control is outside the viewport or the host cannot tell.
+    hit_test_reachable: bool | None = None
+    duplicate_id: bool = False
+
+
+class BrowserObservation(Contract):
+    schema_version: Literal["ksadk.browser-observation/v1"] = "ksadk.browser-observation/v1"
+    session_ref: BrowserSessionRef
+    action_id: str
+    action_seq: int = Field(ge=0)
+    status: Literal["ok", "error", "uncertain"]
+    error_code: str | None = None
+    complete: bool
+    retryability: Literal["safe", "requires_reconcile", "forbidden"]
+    url: str = ""
+    status_code: int | None = Field(default=None, ge=100, le=599)
+    title: str = ""
+    viewport: tuple[int, int]
+    focus: str = ""
+    # Observed main-frame scroll offsets, not the requested wheel deltas.
+    # A nested scroll container can change while both offsets remain zero.
+    scroll_x: int | None = Field(default=None, strict=True)
+    scroll_y: int | None = Field(default=None, strict=True)
+    lifecycle: str = "unknown"
+    # A failed DOM click under pointer lock needs a different repair from an
+    # overlay or a missing selector. This is observed browser state, not a
+    # model-inferred explanation of the failed action.
+    pointer_lock_active: bool | None = None
+    text: str = ""
+    text_truncated: bool = False
+    # Bounded DOM samples immediately before/after the screenshot differed.
+    # False is not proof of atomic capture or visual stability (e.g. Canvas).
+    # None preserves old/absent observations without inventing such evidence.
+    dom_changed_during_capture: bool | None = None
+    controls: tuple[BrowserControl, ...] = Field(default=(), max_length=40)
+    console: tuple[str, ...] = ()
+    page_errors: tuple[str, ...] = ()
+    page_error_locations: tuple[str, ...] = ()
+    network_failures: tuple[str, ...] = ()
+    logs_truncated: bool = False
+    screenshot: BrowserImage | None = None
+    # Browser-derived text is untrusted data, never system/policy instructions.
+    source_trust: Literal["untrusted_page"] = "untrusted_page"
+
+
+class BrowserRecovery(Contract):
+    status: Literal["reconnected", "restarted", "lost"]
+    session_ref: BrowserSessionRef
+    last_action_seq: int = Field(default=0, ge=0)
+    reason: str | None = None
+    # Host capability: a bound ToolPort rejects old actions and supports a
+    # separately admitted fresh observation. This does not authorize a reset.
+    reobserve_available: bool = Field(default=False, strict=True)
+
+
+def browser_observation_digest(observation: BrowserObservation) -> str:
+    """Hash captured state without action identities or artifact locations.
+
+    Actual page timestamps, errors, focus and controls remain meaningful data.
+    An image's bytes/model block identify it, rather than the artifact sink's
+    path or URI. This is observation novelty, never task completion evidence.
+    """
+    payload = observation.model_dump(
+        mode="json",
+        exclude={
+            "session_ref",
+            "action_id",
+            "action_seq",
+            "screenshot",
+            "dom_changed_during_capture",
+        },
+    )
+    # Reference allocation is targeting metadata, not observed task progress.
+    for control in payload.get("controls", []):
+        control.pop("element_ref", None)
+    if observation.screenshot is not None:
+        screenshot = observation.screenshot
+        payload["screenshot"] = {
+            "mime_type": screenshot.mime_type,
+            "width": screenshot.width,
+            "height": screenshot.height,
+            "image_digest": hashlib.sha256(
+                json.dumps(screenshot.content_block, sort_keys=True).encode()
+            ).hexdigest(),
+        }
+    return (
+        "sha256:"
+        + hashlib.sha256(
+            json.dumps(payload, ensure_ascii=False, sort_keys=True, separators=(",", ":")).encode()
+        ).hexdigest()
+    )