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

ksadk/harness/native/hook_runtime_contract.py

@@ -0,0 +1,282 @@
+"""Native Hook contracts. A Hook can propose data, never grant runtime authority.
+
+This is a new native protocol, not an adapter for the legacy ProviderHook API.
+Dispatch and durable lifecycle admission belong to the Kernel and host Ports.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+from typing import Literal, Protocol
+
+from pydantic import Field, JsonValue, model_validator
+
+from .model import ModelToolCall
+from .state import Contract, RunScope
+
+HookEvent = Literal["PreToolUse", "PostToolUse", "Stop", "PreCompact"]
+HookFailure = Literal[
+    "producer_failed", "producer_invalid", "input_budget_exceeded", "output_budget_exceeded",
+    "producer_timeout", "binding_unavailable", "policy_denied", "policy_error",
+]
+
+
+def _json_bytes(value: object) -> bytes:
+    return json.dumps(
+        value, ensure_ascii=False, sort_keys=True, separators=(",", ":"), allow_nan=False,
+    ).encode("utf-8")
+
+
+def hook_execution_policy_digest(*, cleanup_timeout_seconds: float) -> str:
+    if (type(cleanup_timeout_seconds) not in (int, float)
+            or not math.isfinite(cleanup_timeout_seconds) or cleanup_timeout_seconds <= 0):
+        raise ValueError("Hook cleanup wait must be explicit, finite and positive")
+    policy = {
+        "version": "ksadk.native-hook-callback-lifetime/v1",
+        "cleanup_timeout_seconds": float(cleanup_timeout_seconds),
+    }
+    return "sha256:" + hashlib.sha256(_json_bytes(policy)).hexdigest()
+
+
+class HookDefinition(Contract):
+    hook_id: str = Field(min_length=1, max_length=128, pattern=r"^[a-z0-9._-]+$")
+    source_ref: str = Field(min_length=1, max_length=512)
+    binding_digest: str = Field(pattern=r"^sha256:[0-9a-f]{64}$")
+    execution_policy_digest: str = Field(pattern=r"^sha256:[0-9a-f]{64}$")
+    # Host authority for interpreting unknown callback outcomes. Never inferred
+    # from the Hook's event/name or from model-produced data.
+    read_only: bool = Field(strict=True)
+    events: tuple[HookEvent, ...] = Field(min_length=1, max_length=4)
+    tool_names: tuple[str, ...] | None = None
+    # All I/O limits are explicit host inputs. No invisible timeout or retry.
+    timeout_seconds: float = Field(strict=True, gt=0, allow_inf_nan=False)
+    max_input_bytes: int = Field(strict=True, ge=1)
+    max_output_bytes: int = Field(strict=True, ge=1)
+    failure_mode: Literal["warn", "block"]
+    compaction_source_projection: Literal["canonical_user"] | None = Field(
+        default=None, exclude_if=lambda value: value is None,
+    )
+
+    @model_validator(mode="after")
+    def valid_selection(self):
+        if len(set(self.events)) != len(self.events):
+            raise ValueError("duplicate Hook events")
+        if self.tool_names is not None and (
+            not self.tool_names or any(not name.strip() for name in self.tool_names)
+            or len(set(self.tool_names)) != len(self.tool_names)
+        ):
+            raise ValueError("invalid Hook tool selection")
+        if set(self.events) <= {"Stop", "PreCompact"} and self.tool_names is not None:
+            raise ValueError("lifecycle Hook cannot select tool names")
+        if self.compaction_source_projection is not None and "PreCompact" not in self.events:
+            raise ValueError("compaction projection requires PreCompact")
+        return self
+
+    def matches(self, event: HookEvent, tool_name: str | None = None) -> bool:
+        return event in self.events and (
+            event in {"Stop", "PreCompact"} or self.tool_names is None
+            or tool_name in self.tool_names
+        )
+
+
+class PreCompactSubject(Contract):
+    """The admitted original prefix, before any summary or callback projection."""
+
+    source_revision: int = Field(strict=True, ge=0)
+    source_context_digest: str = Field(pattern=r"^[0-9a-f]{64}$")
+    source_message_count: int = Field(strict=True, ge=0)
+    message_refs: tuple[str, ...]
+    messages: tuple[dict[str, JsonValue], ...]
+    retained_message_refs: tuple[str, ...]
+    source_projection: Literal["canonical_user"] | None = Field(
+        default=None, exclude_if=lambda value: value is None,
+    )
+
+    @model_validator(mode="after")
+    def source_alignment(self):
+        if (len(self.message_refs) != len(self.messages)
+                or len(set(self.message_refs)) != len(self.message_refs)
+                or set(self.message_refs) & set(self.retained_message_refs)):
+            raise ValueError("PreCompact source references do not match its removed messages")
+        return self
+
+
+class HookInvocationRequest(Contract):
+    schema_version: Literal["ksadk.native-hook-request/v1"] = "ksadk.native-hook-request/v1"
+    scope: RunScope
+    run_id: str = Field(min_length=1)
+    session_id: str = Field(min_length=1)
+    turn_id: str = Field(min_length=1)
+    operation_key: str = Field(min_length=1)
+    goal_revision: int = Field(strict=True, ge=0)
+    goal: str = Field(min_length=1)
+    tool_call_count: int = Field(strict=True, ge=0)
+    stop_continuation_count: int = Field(strict=True, ge=0)
+    event: HookEvent
+    definition: HookDefinition
+    call: ModelToolCall | None = None
+    tool_result: dict[str, JsonValue] | None = None
+    candidate_id: str | None = Field(default=None, min_length=1)
+    candidate_text: str | None = None
+    compaction: PreCompactSubject | None = Field(
+        default=None, exclude_if=lambda value: value is None,
+    )
+
+    @model_validator(mode="after")
+    def valid_subject(self):
+        if not self.definition.matches(self.event, self.call.name if self.call else None):
+            raise ValueError("Hook event or tool is outside its definition")
+        if self.event == "PreCompact":
+            if (self.compaction is None or self.call is not None or self.tool_result is not None
+                    or self.candidate_id is not None or self.candidate_text is not None):
+                raise ValueError("PreCompact requires only an admitted compaction source")
+            if self.compaction.source_projection != self.definition.compaction_source_projection:
+                raise ValueError("PreCompact projection differs from its locked definition")
+        elif self.compaction is not None:
+            raise ValueError("only PreCompact may contain a compaction source")
+        elif self.event == "Stop":
+            if (self.call is not None or self.tool_result is not None
+                    or self.candidate_id is None or self.candidate_text is None):
+                raise ValueError("Stop Hook requires only a completion candidate")
+        elif self.call is None or self.candidate_id is not None or self.candidate_text is not None:
+            raise ValueError("tool Hook requires only a tool subject")
+        elif self.event == "PreToolUse" and self.tool_result is not None:
+            raise ValueError("PreToolUse cannot contain an executed result")
+        elif self.event == "PostToolUse":
+            if self.tool_result is None:
+                raise ValueError("PostToolUse requires an executed result")
+            # Lazy import keeps HookDefinition usable by the Port contracts.
+            from .ports import ToolResult
+
+            ToolResult.model_validate(self.tool_result)
+        _json_bytes(self.input_payload())
+        return self
+
+    def input_payload(self) -> dict:
+        payload = {
+            "goal": self.goal,
+            "tool_call_count": self.tool_call_count,
+            "stop_continuation_count": self.stop_continuation_count,
+            "call": self.call.model_dump(mode="json") if self.call else None,
+            "tool_result": self.tool_result,
+            "candidate_id": self.candidate_id,
+            "candidate_text": self.candidate_text,
+        }
+        if self.compaction is not None:
+            payload["compaction"] = self.compaction.model_dump(mode="json")
+        return payload
+
+    @property
+    def input_digest(self) -> str:
+        payload = {
+            "definition": self.definition.model_dump(mode="json"),
+            "input": self.input_payload(),
+        }
+        return "sha256:" + hashlib.sha256(_json_bytes(payload)).hexdigest()
+
+    @property
+    def input_bytes(self) -> int:
+        return len(_json_bytes(self.input_payload()))
+
+    @property
+    def stop_hook_active(self) -> bool:
+        return self.event == "Stop" and self.stop_continuation_count > 0
+
+
+class HookOutput(Contract):
+    action: Literal["continue", "deny", "repair"] = "continue"
+    additional_context: tuple[str, ...] = ()
+    updated_arguments: dict[str, JsonValue] | None = None
+
+    @model_validator(mode="after")
+    def valid_data(self):
+        _json_bytes(self.model_dump(mode="json"))
+        if self.action == "repair" and not any(text.strip() for text in self.additional_context):
+            raise ValueError("Stop repair requires actionable context")
+        return self
+
+
+class HookInvocationResult(Contract):
+    schema_version: Literal["ksadk.native-hook-result/v1"] = "ksadk.native-hook-result/v1"
+    scope: RunScope
+    run_id: str
+    session_id: str
+    turn_id: str
+    operation_key: str
+    goal_revision: int = Field(strict=True, ge=0)
+    event: HookEvent
+    hook_id: str
+    source_ref: str
+    binding_digest: str = Field(pattern=r"^sha256:[0-9a-f]{64}$")
+    input_digest: str = Field(pattern=r"^sha256:[0-9a-f]{64}$")
+    status: Literal["ok", "failed", "uncertain"]
+    output: HookOutput | None = None
+    reason: HookFailure | None = None
+
+    @model_validator(mode="after")
+    def valid_outcome(self):
+        if self.status == "ok":
+            if self.output is None or self.reason is not None:
+                raise ValueError("successful Hook requires only a valid output")
+        elif self.output is not None or self.reason is None:
+            raise ValueError("failed Hook cannot supply an output")
+        if self.output is not None:
+            if self.output.updated_arguments is not None and (
+                self.event != "PreToolUse" or self.output.action != "continue"
+            ):
+                raise ValueError("only a continuing PreToolUse may propose new arguments")
+            if self.output.action == "repair" and self.event != "Stop":
+                raise ValueError("only Stop may request repair")
+        return self
+
+    @classmethod
+    def for_request(
+        cls, request: HookInvocationRequest, *, output: HookOutput | None = None,
+        reason: HookFailure | None = None, uncertain: bool = False,
+    ):
+        return cls(
+            **request.model_dump(include={
+                "scope", "run_id", "session_id", "turn_id", "operation_key",
+                "goal_revision", "event",
+            }),
+            hook_id=request.definition.hook_id, source_ref=request.definition.source_ref,
+            binding_digest=request.definition.binding_digest, input_digest=request.input_digest,
+            status="uncertain" if uncertain else "failed" if reason is not None else "ok",
+            output=output, reason=reason,
+        )
+
+
+class HookPort(Protocol):
+    async def invoke(self, request: HookInvocationRequest) -> HookInvocationResult: ...
+
+
+def validate_hook_result(
+    request: HookInvocationRequest, result: HookInvocationResult,
+) -> HookInvocationResult:
+    # Frozen Pydantic objects contain mutable JSON. Detach/revalidate both
+    # sides, including objects created by model_copy/model_construct.
+    request = HookInvocationRequest.model_validate_json(
+        _json_bytes(request.model_dump(mode="json"))
+    )
+    result = HookInvocationResult.model_validate_json(_json_bytes(result.model_dump(mode="json")))
+    identity = ("scope", "run_id", "session_id", "turn_id", "operation_key",
+                "goal_revision", "event")
+    if any(getattr(request, key) != getattr(result, key) for key in identity):
+        raise ValueError("Hook receipt identity mismatch")
+    if (result.hook_id, result.source_ref, result.binding_digest, result.input_digest) != (
+        request.definition.hook_id, request.definition.source_ref,
+        request.definition.binding_digest, request.input_digest,
+    ):
+        raise ValueError("Hook receipt binding or input mismatch")
+    if request.input_bytes > request.definition.max_input_bytes and not (
+        result.status == "failed" and result.reason == "input_budget_exceeded"
+    ):
+        raise ValueError("Hook input exceeded its declared budget")
+    if result.output is not None and (
+        len(_json_bytes(result.output.model_dump(mode="json")))
+        > request.definition.max_output_bytes
+    ):
+        raise ValueError("Hook output exceeded its declared budget")
+    return result

ksadk/harness/native/interaction_observation.py

@@ -0,0 +1,117 @@
+"""Durable host evidence for browser observations and interaction failures."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+
+from pydantic import JsonValue
+
+from .ports import ToolResult
+
+_INTERACTIVE_ACTIONS = frozenset({"click", "fill", "press", "reload"})
+
+
+def advance_browser_observation(
+    previous: dict[str, JsonValue] | None,
+    *,
+    role: str,
+    tool_call: int,
+    result: ToolResult,
+) -> dict[str, JsonValue] | None:
+    """Remember only a successful screenshot from the host-bound browser port."""
+    if role != "browser" or result.status != "ok" or not isinstance(result.content, dict):
+        return previous
+    content = result.content
+    entry = content.get("entry_path")
+    screenshot = content.get("screenshot_path")
+    if (
+        content.get("ok") is not True
+        or not isinstance(entry, str)
+        or not entry
+        or not isinstance(screenshot, str)
+        or not screenshot
+    ):
+        return previous
+    receipt = json.dumps(
+        {
+            "entry_path": entry,
+            "screenshot_path": screenshot,
+            "browser_session_id": content.get("browser_session_id"),
+            "browser_action_seq": content.get("browser_action_seq"),
+            "tool_call": tool_call,
+        },
+        ensure_ascii=False,
+        sort_keys=True,
+        default=str,
+    ).encode("utf-8")
+    return {
+        "entry_path": entry,
+        "tool_call": tool_call,
+        "evidence_ref": "sha256:" + hashlib.sha256(receipt).hexdigest(),
+        "vision_description_status": str(content.get("vision_description_status") or "not_bound"),
+    }
+
+
+def advance_interaction_observation(
+    previous: dict[str, JsonValue] | None,
+    *,
+    role: str,
+    tool_name: str,
+    tool_call: int,
+    result: ToolResult,
+) -> dict[str, JsonValue] | None:
+    """Clear a page failure only after a successful action on the same entry.
+
+    A later screenshot or host-only reload is insufficient: it can hide an
+    error triggered by the user's original click or key press. The receipt is
+    host supplied, and only a host-tagged browser port participates.
+    """
+    if role != "browser" or not isinstance(result.content, dict):
+        return previous
+    content = result.content
+    entry = content.get("entry_path")
+    if not isinstance(entry, str) or not entry:
+        return previous
+    errors = (
+        item[:300]
+        for key in ("page_errors", "console_errors", "request_failures")
+        for group in (content.get(key),)
+        if isinstance(group, list)
+        for item in group
+        if isinstance(item, str) and item
+    )
+    error = next(errors, None)
+    if result.status == "error" and error is not None:
+        receipt = json.dumps(
+            {"entry_path": entry, "tool_call": tool_call, "content": content},
+            ensure_ascii=False,
+            sort_keys=True,
+            default=str,
+        ).encode("utf-8")
+        return {
+            "tool_name": tool_name,
+            "entry_path": entry,
+            "tool_call": tool_call,
+            "error": error,
+            "evidence_ref": "sha256:" + hashlib.sha256(receipt).hexdigest(),
+        }
+    actions = content.get("actions")
+    interactive = isinstance(actions, list) and any(
+        isinstance(action, dict) and action.get("type") in _INTERACTIVE_ACTIONS
+        for action in actions
+    )
+    if (
+        previous is not None
+        and result.status == "ok"
+        and content.get("ok") is True
+        and content.get("actions_ok") is True
+        and interactive
+        and previous.get("tool_name") == tool_name
+        and previous.get("entry_path") == entry
+    ):
+        return None
+    return previous
+
+
+__all__ = ["advance_browser_observation", "advance_interaction_observation"]

ksadk/harness/native/lease.py

@@ -0,0 +1,103 @@
+"""Local worker ownership for a Native run, separate from loop decisions."""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Awaitable, TypeVar
+from uuid import uuid4
+
+from ksadk.harness.stores.native_contract import LeasedRunStore, RunStore
+
+from .state import RunScope
+
+Result = TypeVar("Result")
+
+
+class RunLeaseController:
+    def __init__(
+        self, store: RunStore, scope: RunScope, *, ttl_seconds: float | None = None
+    ) -> None:
+        if ttl_seconds is not None:
+            if not isinstance(store, LeasedRunStore):
+                raise ValueError("leased Native runs require a durable lease store")
+            if type(ttl_seconds) not in {int, float} or not 0 < ttl_seconds <= 3600:
+                raise ValueError("lease TTL must be positive and at most one hour")
+        self.store = store
+        self.scope = scope
+        self.ttl_seconds = ttl_seconds
+        self.owner_id = uuid4().hex if ttl_seconds is not None else None
+        self._fences: dict[str, int] = {}
+
+    def attached(self, run_id: str) -> bool:
+        return run_id in self._fences
+
+    def acquire(self, run_id: str) -> None:
+        if run_id in self._fences:
+            return
+        if self.ttl_seconds is None:
+            self._fences[run_id] = self.store.acquire(self.scope, run_id)
+        else:
+            self._fences[run_id] = self.store.acquire_lease(
+                self.scope, run_id, owner_id=self.owner_id, ttl_seconds=self.ttl_seconds
+            )
+
+    def token(self, run_id: str) -> int:
+        if run_id not in self._fences:
+            raise ValueError("attach the run before driving it")
+        token = self._fences[run_id]
+        if self.ttl_seconds is not None:
+            self.store.renew_lease(
+                self.scope, run_id, owner_id=self.owner_id,
+                fencing_token=token, ttl_seconds=self.ttl_seconds,
+            )
+        return token
+
+    def release(self, run_id: str) -> None:
+        token = self._fences.get(run_id)
+        if token is None:
+            return
+        if self.ttl_seconds is not None:
+            self.store.release_lease(
+                self.scope, run_id, owner_id=self.owner_id, fencing_token=token
+            )
+        self._fences.pop(run_id)
+
+    async def keep_alive(self, run_id: str, effect: Awaitable[Result]) -> Result:
+        """Renew during owned work or backoff; the Store fences late writes."""
+        if self.ttl_seconds is None:
+            return await effect
+        stopped = asyncio.Event()
+
+        async def heartbeat() -> None:
+            interval = min(10.0, max(0.01, self.ttl_seconds / 3))
+            while True:
+                try:
+                    await asyncio.wait_for(stopped.wait(), timeout=interval)
+                    return
+                except asyncio.TimeoutError:
+                    self.token(run_id)
+
+        task = asyncio.create_task(heartbeat())
+        running = asyncio.ensure_future(effect)
+        # Observe any result after bounded cancellation, including a port that
+        # ignores cancellation. It cannot be returned to the old owner.
+        running.add_done_callback(
+            lambda finished: finished.exception() if not finished.cancelled() else None
+        )
+        try:
+            completed, _ = await asyncio.wait(
+                (running, task), return_when=asyncio.FIRST_COMPLETED
+            )
+            if task in completed:
+                # A renewal error revokes local execution ownership now,
+                # rather than after the external effect happens to return.
+                task.result()
+            return await running
+        finally:
+            stopped.set()
+            if not running.done():
+                running.cancel()
+                # The dispatcher also bounds its own port cancellation. Never
+                # make an uncooperative awaitable defeat lease-loss shutdown.
+                await asyncio.wait((running,), timeout=0.5)
+            await task