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

ksadk/harness/native/artifact_read_capacity.py

@@ -0,0 +1,182 @@
+"""Pure capacity estimates for a declared, canonical artifact read batch.
+
+Estimates are never receipts or facts. They apply only to ordinary completion
+of the current read-only group without intervening commands or host changes.
+The real ContextPlanner remains the hard admission authority after execution.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+
+from .artifact_read_contract import ARTIFACT_READ_DEFINITION
+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
+
+ARTIFACT_CAPACITY_POLICY = "sealed-artifact-batch/v1"
+
+
+@dataclass(frozen=True)
+class ArtifactGroupCapacity:
+    """An estimate in the bound planner's units, not persistent execution state."""
+
+    source_units: int
+    result_message_units: int
+    fixed_tokens: int
+    summary_tokens: int
+    group_size: 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 = snapshot.messages[index]
+    calls = declared["tool_calls"]
+    tail = snapshot.messages[index+1:]
+    if (not calls or len({c["id"] for c in calls}) != len(calls)
+            or len(tail) + len(snapshot.pending_tools) != len(calls)):
+        return None
+    try:
+        arguments = [json.loads(c["function"]["arguments"]) for c in calls]
+        # Duplicate requests can produce a separate loop-warning observation;
+        # their future framing is deliberately outside this bounded quote.
+        if len({json.dumps(a, sort_keys=True) for a in arguments}) != len(calls):
+            return None
+        if any(c["function"]["name"] != "ArtifactRead" for c in 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=c["function"]["name"],
+                                       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"] == "ArtifactRead"
+                        and json.loads(prior["arguments"]) == arguments[0]):
+                    return None
+    except (KeyError, TypeError, ValueError):
+        return None
+    return declared, tail
+
+
+def artifact_group_capacity(snapshot, configuration, driver):
+    """Quote no-command batch completion using the same pure native reducers.
+
+    Receipts, progress digits, capped receipt digests, tool-budget controls and
+    real summary framing are remeasured rather than estimated by fixed magic
+    constants or by guessing the future operation-key revision width.
+    """
+    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 not planner.policy.read_working_set_count
+            or snapshot.phase != RunPhase.EXECUTING_TOOLS):
+        return None
+    group = _declared_group(snapshot)
+    if group is None or not snapshot.pending_tools or not snapshot.pending_intent:
+        return None
+    declared, sealed = group
+    # The planner's retained-source count is a bound on source identities,
+    # not on the number of atomic call groups. The original declared count
+    # is a safe upper bound without pretending overlapping sources are new.
+    if len(declared["tool_calls"]) > planner.policy.read_working_set_count:
+        return None
+    config = effective_run_configuration(configuration, snapshot)
+
+    installed = [t for t in config.tools if t.name == ARTIFACT_READ_DEFINITION.name]
+    if (len(installed) != 1 or installed[0].model_copy(update={"feedback_profile_digest": None})
+            != ARTIFACT_READ_DEFINITION):
+        return None
+    if (snapshot.tool_calls + snapshot.descendant_tool_calls + len(snapshot.pending_tools)
+            > config.limits.max_tool_calls):
+        return None
+    # An intervening committed command breaks this finite no-command estimate.
+    # It must not be disguised by deriving new keys from an old pending intent.
+    if snapshot.pending_intent != f"{snapshot.run_id}:effect:{snapshot.revision}":
+        return None
+    current = snapshot.model_copy(deep=True)
+    first = True
+    remaining = len(snapshot.pending_tools)
+    while current.pending_tools:
+        before = (current.model_copy(update={"revision": current.revision-1,
+                                             "pending_intent": None}) if first else current)
+        prepared = next_transition(before, config)
+        if (prepared is None or not prepared.intents
+                or prepared.intents[0].kind != "tool"):
+            return None
+        intent = prepared.intents[0]
+        if first and intent.operation_key != current.pending_intent:
+            return None
+        current = prepared.snapshot
+        calls = intent.payload.get("calls") or [intent.payload["call"]]
+        # Only synthetic result shapes enter these detached reducers. The
+        # parent intent owns its child intents; never price them as separate
+        # tool groups or execute their ports while making this estimate.
+        results = [ToolResult(status="ok", content={"capacity_call": call["call_id"]})
+                   for call in calls]
+        if intent.payload.get("parallel_readonly") is True:
+            updated = reduce_parallel_readonly_tools(
+                current, ToolResult(status="ok", content={
+                    "batch_results": [result.model_dump(mode="json") for result in results],
+                }), calls, definitions=config.tools,
+            )
+        else:
+            updated = reduce_tool(current, results[0], definition=installed[0])
+        current = commit_transition(current, updated, "effect.received").snapshot
+        first = False
+    completed = next_transition(current, config)
+    if completed is None or completed.snapshot.phase != RunPhase.PREPARING_CONTEXT:
+        return None
+    current = completed.snapshot
+    fixed = []
+    # Novelty can advance anywhere from zero to the remaining call count. A
+    # real tokenizer need not assign monotonic costs across numeric digit runs.
+    for progress in range(snapshot.observed_progress_revision,
+                          snapshot.observed_progress_revision + remaining + 1):
+        projected = current.model_copy(update={"observed_progress_revision": progress})
+        fixed.append(planner.fixed_request_cost(
+            instructions=model_instructions(projected, config),
+            continuity=driver.continuity(projected, config), contract=config.contract,
+            tools=model_tool_surface(projected, config),
+            turn_control=model_turn_control(projected, config),
+        ))
+    profile = config.profile
+    def count(message):
+        return planner.count_model_message(message, profile)
+
+    goal = {"role": "user", "content": snapshot.goal}
+    # Existing sealed receipts are still in this original group. They cannot
+    # disappear from the denominator or be silently charged as older history.
+    size = len(declared["tool_calls"])
+    available = (profile.context_window - profile.max_output_tokens - max(fixed)
+                 - count(goal) - count(declared)
+                 - sum(count(m) for m in snapshot.messages if m.get("role") == "system"))
+    results = min(available - planner.summary_reservation(profile),
+                  planner.policy.read_working_set_max_tokens - count(declared),
+                  planner.policy.read_working_set_total_max_tokens - count(declared))
+    result_units = min(results // size,
+                       (results - sum(count(m) for m in sealed)) // remaining)
+    return ArtifactGroupCapacity(
+        source_units=available // 2 // size, result_message_units=result_units,
+        fixed_tokens=max(fixed), summary_tokens=planner.summary_reservation(profile),
+        group_size=size,
+    )

ksadk/harness/native/artifact_read_contract.py

@@ -0,0 +1,27 @@
+"""Pure, reserved host artifact-reader contract; no adapter or storage effects."""
+
+from .ports import ToolDefinition
+
+ARTIFACT_READ_NAME = "ArtifactRead"
+ARTIFACT_READ_DEFINITION = ToolDefinition(
+    name=ARTIFACT_READ_NAME,
+    description=(
+        "Read a bounded character page from a host-owned ArtifactRef supplied with user input "
+        "or returned by an earlier tool call in this session. Continue with next_offset_chars "
+        "until complete."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "uri": {"type": "string", "minLength": 1},
+            "offset_chars": {"type": "integer", "minimum": 0},
+            "limit_chars": {"type": "integer", "minimum": 1, "maximum": 32000},
+        },
+        "required": ["uri"],
+        "additionalProperties": False,
+    },
+    read_only=True,
+    concurrent_safe=True,
+    progress_observation=True,
+    context_role="artifact_read",
+)

ksadk/harness/native/artifact_runtime.py

@@ -0,0 +1,408 @@
+"""Runtime-owned large tool result governance.
+
+The tool effect remains successful when its observation is too large for model
+context. Exact text is persisted through an injected ArtifactPort; only a
+bounded preview and a typed host reference enter the model view. An explicitly
+locked v3 policy also retains original content in the canonical receipt for
+historical compaction. Artifact I/O stays outside reducers and never grants
+completion or verification authority.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+
+from ksadk.tools.artifact_observation import (
+    ARCHIVE_MODEL_POLICY,
+    ARCHIVE_SEARCH_MODEL_POLICY,
+    CANONICAL_ARCHIVE_MODEL_POLICY,
+    OBSERVED_ARCHIVE_MODEL_POLICY,
+    SOURCE_ARCHIVE_MODEL_POLICY,
+    archived_observation,
+)
+from ksadk.tools.captured_source_artifact import CAPTURED_SOURCE_MIME, encode_captured_source
+
+from .model import ModelImageContent, ModelTextContent
+from .ports import (
+    ArtifactPort,
+    ArtifactRef,
+    ArtifactWriteRequest,
+    ToolModelObservation,
+    ToolRequest,
+    ToolResult,
+)
+
+_ARTIFACT_MIME = "application/vnd.ksadk.tool-result+json"
+_MAX_IMAGES = 8
+
+
+def _json(value: object) -> str:
+    return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+
+
+def _text_payload(result: ToolResult) -> str:
+    return _json(
+        {
+            "status": result.status,
+            "content": result.content,
+            "content_blocks": [
+                block.model_dump(mode="json")
+                for block in result.content_blocks
+                if not isinstance(block, ModelImageContent)
+            ],
+        }
+    )
+
+
+def _preview(text: str, max_bytes: int) -> str:
+    encoded = text.encode("utf-8")
+    budget = max(64, min(8192, max_bytes // 3))
+    if len(encoded) <= budget:
+        return text
+    half = max(1, budget // 2)
+    return (
+        encoded[:half].decode("utf-8", errors="ignore")
+        + "\n…[middle omitted]…\n"
+        + encoded[-half:].decode("utf-8", errors="ignore")
+    )
+
+
+def _valid_ref(ref: ArtifactRef, content: str, mime_type: str = _ARTIFACT_MIME) -> bool:
+    encoded = content.encode("utf-8")
+    return (
+        ref.size_bytes == len(encoded)
+        and ref.content_hash == "sha256:" + hashlib.sha256(encoded).hexdigest()
+        and ref.mime_type == mime_type
+    )
+
+
+def _bounded_content(content: dict, status: str, max_bytes: int) -> dict:
+    """Reserve disclosure and the locator before fitting a text preview."""
+
+    def size(value: dict) -> int:
+        # The reducer uses the ordinary JSON envelope, including its spaces.
+        return len(json.dumps({"status": status, "content": value}, ensure_ascii=False).encode())
+
+    if size(content) <= max_bytes:
+        return content
+    compact = {key: value for key, value in content.items() if key != "preview"}
+    if "artifact" in compact:
+        compact["artifact"] = {"uri": compact["artifact"]["uri"]}
+        compact["instruction"] = "Use ArtifactRead to read the saved text."
+    else:
+        compact["instruction"] = "Use a narrower request to read the full text."
+    if "media_observation" in compact:
+        compact["media_observation"] = {
+            "image_observation_status": "not_observed",
+            "instruction": compact["media_observation"]["instruction"],
+        }
+    if size(compact) > max_bytes:
+        # A locator which cannot fit must not be admitted as available.
+        raise ValueError("artifact disclosure exceeds result budget")
+    preview = content.get("preview", "")
+    low, high = 0, len(preview)
+    while low < high:
+        mid = (low + high + 1) // 2
+        candidate = {**compact, "preview": preview[:mid] + "…"}
+        if size(candidate) <= max_bytes:
+            low = mid
+        else:
+            high = mid - 1
+    return {**compact, "preview": preview[:low] + "…"} if low else compact
+
+
+async def govern_tool_result(
+    *,
+    request: ToolRequest,
+    result: ToolResult,
+    artifacts: ArtifactPort | None,
+    max_result_bytes: int,
+    max_image_bytes: int,
+) -> ToolResult:
+    """Return a detached, bounded model observation with trusted refs only."""
+
+    # ArtifactRef is runtime authority. A tool callback may return similarly
+    # shaped JSON as content, but cannot add to the trusted snapshot ledger.
+    clean = ToolResult.model_validate_json(
+        result.model_copy(update={"artifact_refs": ()}).model_dump_json()
+    )
+    if request.definition.result_disclosure_policy == "mcp-default/v1":
+        from .mcp_result_governance import govern_mcp_disclosure
+
+        governed = await govern_mcp_disclosure(
+            request=request, result=clean, artifacts=artifacts, payload=_text_payload(clean),
+            max_result_bytes=max_result_bytes, max_image_bytes=max_image_bytes,
+        )
+        if governed is not None:
+            return governed
+    if clean.model_observation is not None:
+        if request.definition.result_model_policy == clean.model_observation.version:
+            return await _govern_typed_observation(
+                request=request, result=clean, artifacts=artifacts,
+                max_result_bytes=min(max_result_bytes, 65536), max_image_bytes=max_image_bytes,
+            )
+        # Missing host policy cannot grant an alternate view. Fall back to
+        # governance of the original known result, without repeating its effect.
+        clean = clean.model_copy(update={"model_observation": None})
+    images = tuple(block for block in clean.content_blocks if isinstance(block, ModelImageContent))
+    media_bytes = sum(len(_json(image.model_dump(mode="json")).encode("utf-8")) for image in images)
+    media_observation = None
+    if media_bytes > max_image_bytes or len(images) > _MAX_IMAGES:
+        # Refuse the images, not the already observed execution fact. Turning
+        # a successful mutation into an error here invites duplicate effects.
+        media_observation = {
+            "code": "tool_media_too_large",
+            "image_observation_status": "not_observed",
+            "image_count": len(images),
+            "original_bytes": media_bytes,
+            "limit_bytes": max_image_bytes,
+            "instruction": (
+                "Images were not observed (media budget). Do not repeat solely for missing "
+                "images; use a smaller read-only observation."
+            ),
+        }
+        model_content = clean.model_content
+        if model_content is not None:
+            try:
+                view = json.loads(model_content)
+            except ValueError:
+                view = None
+            model_content = (
+                _json({**view, "media_observation": media_observation})
+                if isinstance(view, dict)
+                else model_content + "\n" + _json(media_observation)
+            )
+        clean = clean.model_copy(
+            update={
+                "model_content": model_content,
+                "content_blocks": (
+                    *(b for b in clean.content_blocks if not isinstance(b, ModelImageContent)),
+                    ModelTextContent(text=_json(media_observation)),
+                ),
+            }
+        )
+        images = ()
+    # A callback cannot use the alternate model view to bypass this Run's
+    # observation budget when the auditable raw result happens to be small.
+    # The omission disclosure above must fit this same bound.
+    if clean.model_content is not None and len(clean.model_content.encode("utf-8")) > min(
+        max_result_bytes, 65536
+    ):
+        clean = clean.model_copy(update={"model_content": None})
+
+    payload = _text_payload(clean)
+    original_bytes = len(payload.encode("utf-8"))
+    archive_required = (
+        request.definition.result_archive_policy
+        in {
+            ARCHIVE_MODEL_POLICY,
+            ARCHIVE_SEARCH_MODEL_POLICY,
+            CANONICAL_ARCHIVE_MODEL_POLICY,
+            OBSERVED_ARCHIVE_MODEL_POLICY,
+            SOURCE_ARCHIVE_MODEL_POLICY,
+        }
+        and clean.status == "ok"
+    )
+    preserve_view = archive_required and clean.model_content is not None
+    archive_policy = request.definition.result_archive_policy or ARCHIVE_MODEL_POLICY
+    archive_payload, archive_mime = payload, _ARTIFACT_MIME
+    if archive_policy == SOURCE_ARCHIVE_MODEL_POLICY:
+        source = encode_captured_source(clean.content)
+        if source is not None:
+            archive_payload, archive_mime = source, CAPTURED_SOURCE_MIME
+    if preserve_view:
+        try:
+            archived_observation(clean.model_content, None, policy=archive_policy)
+        except (ValueError, TypeError):
+            preserve_view = False
+    if original_bytes <= max_result_bytes and not archive_required:
+        return clean
+
+    def offloaded_content(ref: ArtifactRef | None) -> dict:
+        content = {
+            "code": "tool_result_offloaded" if ref is not None else "tool_result_truncated",
+            "execution_status": clean.status,
+            "original_bytes": original_bytes,
+            "preview": _preview(
+                clean.model_content if preserve_view else payload, max_result_bytes
+            ),
+            "artifact_state": "available" if ref is not None else "unavailable",
+            "instruction": (
+                "Use ArtifactRead with the artifact URI to read bounded pages."
+                if ref is not None
+                else "The full result could not be persisted; use a narrower tool request."
+            ),
+        }
+        if ref is not None:
+            content["artifact"] = ref.model_dump(mode="json")
+        else:
+            content["limit_bytes"] = max_result_bytes
+        if media_observation is not None:
+            content["media_observation"] = media_observation
+        return _bounded_content(content, clean.status, max_result_bytes)
+
+    ref: ArtifactRef | None = None
+    if artifacts is not None:
+        try:
+            written = await artifacts.write(
+                ArtifactWriteRequest(
+                    scope=request.scope,
+                    run_id=request.run_id,
+                    operation_key=request.operation_key,
+                    tool_call_id=request.call.call_id,
+                    tool_name=request.call.name,
+                    content=archive_payload,
+                    mime_type=archive_mime,
+                )
+            )
+            candidate = ArtifactRef.model_validate_json(written.model_dump_json())
+            if not _valid_ref(candidate, archive_payload, archive_mime):
+                raise ValueError("artifact receipt does not bind persisted content")
+            if preserve_view:
+                # Validate the complete bounded projection before admitting the
+                # reference. An invalid/overlong locator must not enter context.
+                projected = archived_observation(
+                    clean.model_content, candidate.uri, policy=archive_policy
+                )
+                if len(projected.encode("utf-8")) > max_result_bytes:
+                    raise ValueError("archive model view exceeds result budget")
+            else:
+                offloaded_content(candidate)
+            ref = candidate
+        except Exception:
+            # ZCode's result serialization falls back to bounded truncation when
+            # persistence fails. Preserve the actual execution status and never
+            # leak the full payload into context.
+            pass
+
+    content = offloaded_content(ref)
+    model_content = (
+        archived_observation(
+            clean.model_content, ref.uri if ref is not None else None, policy=archive_policy
+        )
+        if preserve_view
+        else None
+    )
+    if model_content is not None and len(model_content.encode("utf-8")) > max_result_bytes:
+        model_content = None
+    canonical = (
+        archive_policy
+        in {
+            CANONICAL_ARCHIVE_MODEL_POLICY,
+            OBSERVED_ARCHIVE_MODEL_POLICY,
+            SOURCE_ARCHIVE_MODEL_POLICY,
+        }
+        and clean.status == "ok"
+    )
+    if canonical and model_content is None:
+        model_content = _json({"status": clean.status, "content": content})
+    observation_digest = clean.progress_observation_digest
+    if observation_digest is None and preserve_view:
+        # A newly issued storage locator is not new source evidence. Compare
+        # the original model observation, excluding this operation's URI.
+        observation_digest = (
+            "sha256:"
+            + hashlib.sha256(_json(json.loads(clean.model_content)).encode("utf-8")).hexdigest()
+        )
+    return ToolResult(
+        status=clean.status,
+        progress_observation_digest=observation_digest,
+        content=clean.content if canonical else content,
+        model_content=model_content,
+        content_blocks=clean.content_blocks if canonical else images,
+        artifact_refs=(ref,) if ref is not None else (),
+        resource_usage=clean.resource_usage,
+        child_budget_reservation=clean.child_budget_reservation,
+        child_budget_settlement=clean.child_budget_settlement,
+        workspace_changed_paths=clean.workspace_changed_paths,
+        browser_session_ref=clean.browser_session_ref,
+        browser_session_closed=clean.browser_session_closed,
+        interaction_id=clean.interaction_id,
+    )
+
+
+async def _govern_typed_observation(
+    *, request: ToolRequest, result: ToolResult, artifacts: ArtifactPort | None,
+    max_result_bytes: int, max_image_bytes: int,
+) -> ToolResult:
+    observation = result.model_observation
+    images = tuple(b for b in observation.content_blocks if isinstance(b, ModelImageContent))
+    media_bytes = sum(len(_json(b.model_dump(mode="json")).encode()) for b in images)
+    warning = None
+    if media_bytes > max_image_bytes or len(images) > _MAX_IMAGES:
+        warning = {
+            "image_observation_status": "not_observed",
+            "instruction": "Images were not observed. Do not repeat solely for missing images.",
+        }
+        content = {"observation": observation.content, "media_observation": warning}
+        observation = observation.model_copy(update={
+            "content": content,
+            "content_blocks": tuple(
+                b for b in observation.content_blocks if not isinstance(b, ModelImageContent)
+            ),
+        })
+        images = ()
+
+    def text_size(value: ToolModelObservation) -> int:
+        return len(json.dumps({"status": value.status, "content": value.content},
+                              ensure_ascii=False).encode()) + sum(
+            len(_json(b.model_dump(mode="json")).encode()) + 1
+            for b in value.content_blocks if isinstance(b, ModelTextContent)
+        )
+
+    raw = _text_payload(result)
+    original_bytes = len(raw.encode())
+    if original_bytes <= max_result_bytes and text_size(observation) <= max_result_bytes:
+        return result.model_copy(update={"model_observation": observation})
+
+    # The saved receipt is exact. The model preview comes from the textual
+    # observation, never from the raw envelope containing binary base64.
+    preview_source = json.dumps(observation.content, ensure_ascii=False) + "\n" + "\n".join(
+        b.text for b in observation.content_blocks if isinstance(b, ModelTextContent)
+    )
+
+    def bounded(ref: ArtifactRef | None) -> ToolModelObservation:
+        content = {
+            "code": "tool_result_offloaded" if ref is not None else "tool_result_truncated",
+            "execution_status": result.status,
+            "artifact_state": "available" if ref is not None else "unavailable",
+            "original_bytes": original_bytes,
+            "preview": _preview(preview_source, max_result_bytes),
+            "instruction": (
+                "Use ArtifactRead to read the saved result; binary JSON is not visual evidence."
+                if ref is not None
+                else "Full result unavailable; use a narrower read-only observation."
+            ),
+        }
+        if ref is not None:
+            content["artifact"] = ref.model_dump(mode="json")
+        if warning is not None:
+            content["media_observation"] = warning
+        return ToolModelObservation(
+            status=result.status,
+            content=_bounded_content(content, result.status, max_result_bytes),
+            content_blocks=images,
+        )
+
+    ref = None
+    if artifacts is not None:
+        try:
+            written = await artifacts.write(ArtifactWriteRequest(
+                scope=request.scope, run_id=request.run_id, operation_key=request.operation_key,
+                tool_call_id=request.call.call_id, tool_name=request.call.name,
+                content=raw, mime_type=_ARTIFACT_MIME,
+            ))
+            candidate = ArtifactRef.model_validate_json(written.model_dump_json())
+            if not _valid_ref(candidate, raw):
+                raise ValueError("artifact receipt does not bind persisted content")
+            bounded(candidate)
+            ref = candidate
+        except Exception:
+            pass
+    return result.model_copy(update={
+        "model_observation": bounded(ref), "artifact_refs": (ref,) if ref is not None else (),
+    })
+
+
+__all__ = ["govern_tool_result"]