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

ksadk/harness/native/browser_recovery.py

@@ -0,0 +1,183 @@
+"""Pure browser ownership admission; restored pages never inherit old evidence."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+from pydantic import JsonValue
+
+from .browser_contract import BrowserRecovery, BrowserSessionRef
+from .state import RunPhase, RunSnapshot
+from .transitions import commit_transition, finish
+
+if TYPE_CHECKING:
+    from .ports import ToolResult
+
+
+def remember_browser(
+    snapshot: RunSnapshot, ref: BrowserSessionRef, *, closed: bool = False
+) -> RunSnapshot:
+    if ref.scope != snapshot.scope or ref.run_id != snapshot.run_id:
+        return finish(snapshot, "failed", "browser_reference_scope_mismatch")
+    if closed:
+        # An old session's close must not erase a newer owner/generation.
+        return snapshot.model_copy(update={
+            "browser_session_refs": tuple(
+                item for item in snapshot.browser_session_refs
+                if item != ref.model_dump(mode="json")
+            ),
+        })
+    refs = tuple(
+        item for item in snapshot.browser_session_refs if item.get("runtime_id") != ref.runtime_id
+    )
+    if len(refs) >= 16:
+        return finish(snapshot, "failed", "browser_reference_limit")
+    return snapshot.model_copy(
+        update={
+            "browser_session_refs": (*refs, ref.model_dump(mode="json")),
+        }
+    )
+
+
+def recovery_transition(snapshot: RunSnapshot, reports: tuple[BrowserRecovery, ...]):
+    refs = tuple(BrowserSessionRef.model_validate(item) for item in snapshot.browser_session_refs)
+    if len(reports) != len(refs):
+        raise ValueError("browser recovery must account for every bound reference")
+    events = []
+    for original, report in zip(refs, reports, strict=True):
+        recovered = report.session_ref
+        if original.scope != snapshot.scope or original.run_id != snapshot.run_id:
+            raise ValueError("persisted browser scope mismatch")
+        expected = (
+            original
+            if report.status != "restarted"
+            else original.model_copy(
+                update={
+                    "generation": original.generation + 1,
+                    "lease_epoch": original.lease_epoch + 1,
+                }
+            )
+        )
+        if recovered != expected:
+            raise ValueError("browser recovery reference mismatch")
+        events.append(
+            (
+                "browser.recovered",
+                {
+                    "session_id": recovered.session_id,
+                    "runtime_id": recovered.runtime_id,
+                    "status": report.status,
+                    "generation": recovered.generation,
+                    "lease_epoch": recovered.lease_epoch,
+                    "last_action_seq": report.last_action_seq,
+                    "reason": report.reason,
+                    "reobserve_available": report.reobserve_available,
+                },
+            )
+        )
+    missing = not refs and snapshot.last_browser_observation is not None
+    if missing:
+        events.append(
+            (
+                "browser.recovered",
+                {
+                    "status": "lost",
+                    "reason": "browser_reference_missing",
+                },
+            )
+        )
+    if not events:
+        return None
+    unavailable = missing or any(report.status != "reconnected" for report in reports)
+    updated = snapshot
+    if unavailable:
+        safe_reobserve = (
+            not missing
+            and snapshot.phase in {RunPhase.PREPARING_CONTEXT, RunPhase.EXECUTING_TOOLS}
+            and snapshot.pending_intent is None
+            and not snapshot.pending_tools
+            and all(
+                report.status == "reconnected"
+                or (report.status == "lost" and report.reobserve_available)
+                for report in reports
+            )
+        )
+        updated = (
+            snapshot
+            if safe_reobserve
+            else finish(snapshot, "unverified", "browser_session_unavailable")
+        ).model_copy(
+            update={
+                "last_browser_observation": None,
+                "last_browser_attempt_tool_call": None,
+                "prepared_context": None,
+                "candidate": None,
+                "verification": None,
+                "verification_tool_calls": None,
+                "delivery_review": None,
+                "final_text": "",
+            }
+        )
+        if safe_reobserve:
+            updated = updated.model_copy(
+                update={
+                    "phase": RunPhase.PREPARING_CONTEXT,
+                    "browser_reobservation_refs": tuple(
+                        report.session_ref.model_dump(mode="json")
+                        for report in reports
+                        if report.status == "lost"
+                    ),
+                    "messages": (
+                        *snapshot.messages,
+                        {
+                            "role": "user",
+                            "kind": "browser_recovery_observation",
+                            "content": json.dumps(
+                                {
+                                    "status": "lost",
+                                    "page_continuity": False,
+                                    "prior_observation_valid": False,
+                                    "fresh_observation_required": True,
+                                },
+                                sort_keys=True,
+                            ),
+                        },
+                    ),
+                }
+            )
+            events.append(
+                (
+                    "browser.reobservation_required",
+                    {
+                        "prior_observation_valid": False,
+                        "old_actions_replayed": False,
+                    },
+                )
+            )
+    return commit_transition(
+        snapshot, updated, events[0][0], events[0][1], extra_events=tuple(events[1:])
+    )
+
+
+def remaining_reobservations(
+    snapshot: RunSnapshot,
+    result: ToolResult,
+    observation: dict[str, JsonValue] | None,
+) -> tuple[dict[str, JsonValue], ...]:
+    """Only a successful typed replacement observation retires resource debt."""
+    ref = result.browser_session_ref
+    if (
+        result.status != "ok"
+        or ref is None
+        or observation is None
+        or observation.get("tool_call") != snapshot.tool_calls + 1
+    ):
+        return snapshot.browser_reobservation_refs
+    original = ref.model_copy(
+        update={
+            "generation": ref.generation - 1,
+            "lease_epoch": ref.lease_epoch - 1,
+        }
+    ).model_dump(mode="json")
+    return tuple(old for old in snapshot.browser_reobservation_refs if old != original)

ksadk/harness/native/capabilities.py

@@ -0,0 +1,204 @@
+"""Host-admitted capability views and per-call fences, independent of plugins.
+
+This is an execution projection, never an install format or lifecycle owner.
+The authority callback must query the owning host for this exact activation;
+the currently active *new* profile is not the status of an older retained run.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Sequence
+from dataclasses import dataclass
+
+from pydantic import Field, model_validator
+
+from .adapters import StrictToolExecutor, ToolAuthorizer, ToolBinding, _snapshot
+from .ports import ToolDefinition, ToolPort, ToolRequest, ToolResult
+from .state import Contract, RunScope
+
+_SHA256 = r"^sha256:[0-9a-f]{64}$"
+
+
+class CapabilityUnavailable(ValueError):
+    """Safe, stable admission failure without plugin exception/credential text."""
+
+    def __init__(self, code: str) -> None:
+        self.code = code
+        super().__init__(code)
+
+
+class ActivationPin(Contract):
+    scope: RunScope
+    run_id: str = Field(min_length=1)
+    profile_digest: str = Field(pattern=_SHA256)
+    plugin_lock_digest: str = Field(pattern=_SHA256)
+    activation_key: str = Field(min_length=1)
+    generation: str = Field(min_length=1)
+
+
+class CapabilityPin(Contract):
+    plugin_id: str = Field(min_length=1)
+    plugin_version: str = Field(min_length=1)
+    plugin_digest: str = Field(pattern=_SHA256)
+    definition: str = Field(pattern=r"^[a-z][a-z0-9._-]*/v[1-9][0-9]*$")
+    slot: str = Field(min_length=1)
+    required_permissions: tuple[str, ...] = ()
+
+    @property
+    def identity(self) -> tuple[str, str, str]:
+        return self.plugin_id, self.definition, self.slot
+
+
+class CapabilityInventory(Contract):
+    activation: ActivationPin
+    capabilities: tuple[CapabilityPin, ...]
+    granted_permissions: tuple[str, ...] = ()
+
+    @model_validator(mode="after")
+    def unique_capabilities(self) -> CapabilityInventory:
+        if len({pin.identity for pin in self.capabilities}) != len(self.capabilities):
+            raise ValueError("duplicate capability identity")
+        return self
+
+
+class CapabilityStatus(Contract):
+    inventory: CapabilityInventory
+    available: bool = False
+    revoked: bool = False
+
+
+CapabilityProbe = Callable[[ActivationPin], Awaitable[CapabilityStatus]]
+
+
+@dataclass(frozen=True)
+class CapabilityContribution:
+    pin: CapabilityPin
+    tools: tuple[ToolDefinition, ...]
+    tool_port: ToolPort
+    # Only host-reviewed instructions belong here, never tool-returned text.
+    trusted_instructions: tuple[str, ...] = ()
+
+
+class AdmittedCapabilities:
+    """Immutable model view plus a ToolPort with current host/policy checks.
+
+    The supplied ports are already owned and fenced by the host. A probe cannot
+    replace a generation-bound transport's atomic revocation check: the port
+    must retain the host's lease/fence through the effect. No lifecycle method,
+    credential service, Kernel or writable RunStore is passed to a plugin here.
+    """
+
+    def __init__(
+        self,
+        *,
+        inventory: CapabilityInventory,
+        contributions: Sequence[CapabilityContribution],
+        probe: CapabilityProbe,
+        authorize: ToolAuthorizer | None,
+        max_result_bytes: int = 65536,
+    ) -> None:
+        self._inventory = _snapshot(inventory)
+        self._probe = probe
+        self._authorize = authorize
+        self._tools: tuple[ToolDefinition, ...] = tuple(
+            _snapshot(tool) for contribution in contributions for tool in contribution.tools
+        )
+        self._instructions = tuple(
+            text for contribution in contributions for text in contribution.trusted_instructions
+        )
+        expected = {pin.identity: pin for pin in self._inventory.capabilities}
+        bindings: list[ToolBinding] = []
+        seen: set[tuple[str, str, str]] = set()
+        for contribution in contributions:
+            pin = _snapshot(contribution.pin)
+            if expected.get(pin.identity) != pin or pin.identity in seen:
+                raise CapabilityUnavailable("capability_contribution_mismatch")
+            seen.add(pin.identity)
+            if any(
+                type(text) is not str or not text.strip()
+                for text in contribution.trusted_instructions
+            ):
+                raise CapabilityUnavailable("capability_instructions_invalid")
+            bindings.extend(
+                ToolBinding(_snapshot(tool), self._callback(contribution.tool_port))
+                for tool in contribution.tools
+            )
+        try:
+            self._executor = StrictToolExecutor(
+                scope=inventory.activation.scope,
+                tools=bindings,
+                authorize=self._policy,
+                max_result_bytes=max_result_bytes,
+            )
+        except ValueError:
+            raise CapabilityUnavailable("capability_tool_schema_invalid") from None
+
+    @property
+    def inventory(self) -> CapabilityInventory:
+        return _snapshot(self._inventory)
+
+    @property
+    def model_tools(self) -> tuple[ToolDefinition, ...]:
+        return tuple(_snapshot(tool) for tool in self._tools)
+
+    @property
+    def trusted_instructions(self) -> tuple[str, ...]:
+        return self._instructions
+
+    async def check_available(self) -> None:
+        try:
+            raw = await self._probe(_snapshot(self._inventory.activation))
+            if not isinstance(raw, CapabilityStatus):
+                raise ValueError("invalid status")
+            current = _snapshot(raw)
+        except Exception:
+            raise CapabilityUnavailable("capability_status_unavailable") from None
+        if current.revoked:
+            raise CapabilityUnavailable("capability_revoked")
+        if not current.available:
+            raise CapabilityUnavailable("capability_unavailable")
+        if current.inventory.activation != self._inventory.activation:
+            raise CapabilityUnavailable("activation_mismatch")
+        old = {pin.identity: pin for pin in self._inventory.capabilities}
+        new = {pin.identity: pin for pin in current.inventory.capabilities}
+        if old != new:
+            raise CapabilityUnavailable("capability_drift")
+        required = {permission for pin in old.values() for permission in pin.required_permissions}
+        if not required.issubset(current.inventory.granted_permissions):
+            raise CapabilityUnavailable("capability_permission_unavailable")
+
+    @staticmethod
+    def _denied(code: str) -> ToolResult:
+        return ToolResult(status="error", content={"code": code})
+
+    async def _policy(self, request: ToolRequest):
+        # StrictToolExecutor validates scope, schema and definition first.
+        if self._authorize is None:
+            return "deny"
+        return await self._authorize(request)
+
+    def _callback(self, port: ToolPort):
+        async def dispatch(request: ToolRequest) -> ToolResult:
+            # Policy/approval may have yielded; never reuse its earlier host view.
+            try:
+                await self.check_available()
+            except CapabilityUnavailable as error:
+                return self._denied(error.code)
+            return await port.execute(request)
+
+        return dispatch
+
+    async def execute(self, request: ToolRequest) -> ToolResult:
+        try:
+            sealed = _snapshot(request)
+        except Exception:
+            return self._denied("invalid_tool_request")
+        if sealed.scope != self._inventory.activation.scope:
+            return self._denied("scope_mismatch")
+        if sealed.run_id != self._inventory.activation.run_id:
+            return self._denied("run_mismatch")
+        try:
+            await self.check_available()
+        except CapabilityUnavailable as error:
+            return self._denied(error.code)
+        return await self._executor.execute(sealed)

ksadk/harness/native/child_approval.py

@@ -0,0 +1,60 @@
+"""Pure admission/projection of a host-owned, already reserved child's pause."""
+
+import hashlib
+import json
+
+from .state import ChildApproval, RunPhase, move
+
+
+def host_id(approval: ChildApproval) -> str:
+    return (
+        "native-child-"
+        + hashlib.sha256(
+            json.dumps(approval.model_dump(mode="json"), sort_keys=True).encode()
+        ).hexdigest()
+    )
+
+
+def validate_child_approval(snapshot, approval: ChildApproval) -> None:
+    validate_approval_allocation(snapshot.child_budget_reservations, approval)
+
+
+def validate_approval_allocation(reservations, approval: ChildApproval) -> None:
+    if not any(
+        item.child_run_id == approval.child_run_id
+        and item.child_scope == approval.child_scope
+        and item.parent_operation_key == approval.parent_operation_key
+        and item.parent_tool_call_id == approval.parent_tool_call_id
+        and item.settled_usage_digest is None
+        for item in reservations
+    ):
+        raise ValueError("child_approval_not_reserved")
+
+
+def stage_child_approval(snapshot, approval, *, operation_key, resume_phase):
+    validate_child_approval(snapshot, approval)
+    return move(snapshot, RunPhase.AWAITING_INTERACTION).model_copy(
+        update={
+            "resume_phase": resume_phase,
+            "pending_interaction": operation_key + ":approval",
+            "interaction_host_id": host_id(approval),
+            "interaction": None,
+            "child_approval": approval,
+        }
+    )
+
+
+def approval_event(snapshot):
+    approval = snapshot.child_approval
+    return "approval.requested", {
+        "approval_id": snapshot.pending_interaction,
+        "call_id": approval.tool_call.call_id,
+        "kind": "tool",
+        "detail": {
+            "tool_name": approval.tool_call.name,
+            "arguments": approval.tool_call.arguments,
+            "source": "child_tool",
+            "child_run_id": approval.child_run_id,
+            "child_scope": approval.child_scope.model_dump(mode="json"),
+        },
+    }

ksadk/harness/native/child_budget.py

@@ -0,0 +1,136 @@
+"""Pure parent allocation accounting; child executors never write this ledger."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+
+from .ports import ToolDefinition, ToolRequest, ToolResourceUsage, ToolResult
+from .state import RunSnapshot
+
+
+def _settlement_digest(result: ToolResult) -> str:
+    return hashlib.sha256(
+        json.dumps(
+            {
+                "settlement": result.child_budget_settlement.model_dump(mode="json"),
+                "usage": result.resource_usage.model_dump(mode="json"),
+            },
+            sort_keys=True,
+            separators=(",", ":"),
+        ).encode()
+    ).hexdigest()
+
+
+def validate_child_budget_admission(request: ToolRequest, result: ToolResult) -> None:
+    reservation = result.child_budget_reservation
+    if reservation is None:
+        return
+    remaining = request.budget
+    model_slots = remaining.max_model_calls_remaining - (
+        0 if remaining.parent_finalization_reserved else 1
+    )
+    if (
+        request.definition.child_budget_policy not in {"start/v1", "delegate/v1"}
+        or reservation.parent_operation_key != request.operation_key
+        or reservation.parent_tool_call_id != request.call.call_id
+        or reservation.max_model_calls > model_slots
+        or reservation.max_tool_calls + (
+            # Dispatcher grants already exclude the invoking parent calls.
+            # Legacy start also reserves an explicit collection/control slot;
+            # owned delegates use host collection without an extra tool fee.
+            0 if request.definition.child_budget_policy == "delegate/v1" else 1
+        ) > remaining.max_tool_calls_remaining
+    ):
+        # An owner breached its admission contract after dispatch. Do not
+        # silently accept this or encourage a second, unaccounted launch.
+        raise ValueError("child_budget_start_exceeds_admission")
+
+
+def apply_child_budget(
+    snapshot: RunSnapshot,
+    result: ToolResult,
+    definition: ToolDefinition | None,
+    *,
+    parent_operation_key: str | None = None,
+    parent_tool_call_id: str | None = None,
+) -> tuple[RunSnapshot, ToolResourceUsage]:
+    """Return the ledger and the actual delta owed by this receipt.
+
+    Model-visible JSON cannot create reservations or release them. Repeated
+    collection preserves its own tool cost but has zero descendant usage.
+    """
+    reservation, settlement = result.child_budget_reservation, result.child_budget_settlement
+    if reservation is not None:
+        if definition is None or definition.child_budget_policy not in {"start/v1", "delegate/v1"}:
+            raise ValueError("child_budget_start_not_admitted")
+        operation = parent_operation_key or snapshot.pending_intent
+        call_id = parent_tool_call_id or (
+            snapshot.pending_tools[0]["call_id"] if snapshot.pending_tools else None
+        )
+        if (
+            reservation.parent_operation_key != operation
+            or reservation.parent_tool_call_id != call_id
+            or any(
+                getattr(reservation.child_scope, key) != getattr(snapshot.scope, key)
+                for key in ("tenant_id", "workspace_id", "user_id")
+            )
+            or reservation.child_run_id == snapshot.run_id
+            or any(
+                child.child_run_id == reservation.child_run_id
+                or child.parent_operation_key == reservation.parent_operation_key
+                for child in snapshot.child_budget_reservations
+            )
+            or reservation.child_run_id in snapshot.child_run_ids
+        ):
+            raise ValueError("child_budget_start_identity_conflict")
+        snapshot = snapshot.model_copy(
+            update={
+                "child_budget_reservations": (*snapshot.child_budget_reservations, reservation),
+                "child_run_ids": (*snapshot.child_run_ids, reservation.child_run_id),
+            }
+        )
+    if settlement is None:
+        # A receipt for an allocated child must use settlement identity. It
+        # cannot charge that usage through the older synchronous receipt path.
+        if any(
+            child.child_run_id in result.resource_usage.child_run_ids
+            for child in snapshot.child_budget_reservations
+        ):
+            raise ValueError("child_budget_settlement_identity_required")
+        return snapshot, result.resource_usage
+    if definition is None or definition.child_budget_policy != "settle/v1":
+        raise ValueError("child_budget_settlement_not_admitted")
+    reserved = next(
+        (
+            child
+            for child in snapshot.child_budget_reservations
+            if child.child_run_id == settlement.child_run_id
+        ),
+        None,
+    )
+    usage = result.resource_usage
+    if (
+        reserved is None
+        or reserved.parent_operation_key != settlement.parent_operation_key
+        or reserved.child_request_digest != settlement.child_request_digest
+        or usage.child_run_ids.count(settlement.child_run_id) != 1
+        or usage.model_calls > reserved.max_model_calls
+        or usage.tool_calls > reserved.max_tool_calls
+    ):
+        raise ValueError("child_budget_settlement_identity_or_limit_conflict")
+    sealed = _settlement_digest(result)
+    if reserved.settled_usage_digest is not None:
+        if reserved.settled_usage_digest != sealed:
+            raise ValueError("child_budget_settlement_changed")
+        return snapshot, ToolResourceUsage()
+    return snapshot.model_copy(
+        update={
+            "child_budget_reservations": tuple(
+                child.model_copy(update={"settled_usage_digest": sealed})
+                if child == reserved
+                else child
+                for child in snapshot.child_budget_reservations
+            ),
+        }
+    ), usage

ksadk/harness/native/child_cancellation.py

@@ -0,0 +1,80 @@
+"""Cancel one original owned child, preserving parent execution and accounting."""
+
+from .child_promotion import ChildPromotionInput
+from .state import RunPhase
+from .transitions import commit_transition
+
+
+async def consume_child_cancellation(snapshot, command, *, enabled, port, commit):
+    child_id, reason = None, "child_cancellation_unavailable"
+    if enabled:
+        try:
+            child_id = ChildPromotionInput.model_validate(command.payload).child_run_id
+        except ValueError:
+            reason = "invalid_child_cancellation"
+        else:
+            reason = "requested" if port.can_cancel(snapshot, child_id) else "child_unavailable"
+    target = snapshot
+    extra = ()
+    if reason == "requested":
+        extra = (
+            (
+                "child.cancel_requested",
+                {
+                    "child_run_id": child_id,
+                    "command_id": command.command_id,
+                },
+            ),
+        )
+        approval = snapshot.child_approval
+        if (
+            approval is not None
+            and approval.child_run_id == child_id
+            and snapshot.pending_interaction
+        ):
+            # Cancel this obsolete request, never submit an allow/deny decision
+            # to the protected child tool. An explicit parent pause stays paused.
+            resume = snapshot.resume_phase or RunPhase.EXECUTING_TOOLS
+            updates = {
+                "pending_interaction": None,
+                "interaction_host_id": None,
+                "interaction": None,
+                "child_approval": None,
+                "resume_phase": None,
+            }
+            if snapshot.phase == RunPhase.AWAITING_INTERACTION:
+                updates["phase"] = resume
+            elif (
+                snapshot.phase == RunPhase.PAUSED
+                and snapshot.paused_from == RunPhase.AWAITING_INTERACTION
+            ):
+                updates["paused_from"] = resume
+            target = snapshot.model_copy(update=updates)
+            extra = (
+                *extra,
+                (
+                    "approval.resolved",
+                    {
+                        "approval_id": snapshot.pending_interaction,
+                        "call_id": approval.tool_call.call_id,
+                        "decision": "canceled",
+                        "reason": "child_cancel_requested",
+                    },
+                ),
+            )
+    updated = commit(
+        snapshot,
+        commit_transition(
+            snapshot,
+            target,
+            "command.consumed",
+            {"command_id": command.command_id, "kind": command.kind, "reason": reason},
+            command_id=command.command_id,
+            extra_events=extra,
+        ),
+    )
+    if reason == "requested":
+        # Only revoke the child's locally owned task. Its original runner
+        # settles cancellation and usage; this does not fabricate a terminal.
+        await port.cancel_child(updated, child_id)
+    return updated