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

ksadk/harness/native/precompact_hook_runtime.py

@@ -0,0 +1,171 @@
+"""Receipt-controlled work on original history before a summary can be sent.
+
+Callback data remains low-trust live context. Replan with it under the same
+host budget; callbacks cannot replace summary instructions or acceptance.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+from pydantic import Field, JsonValue
+
+from .context_runtime_contracts import CompactionRequest, _refs, source_context_digest
+from .hook_runtime_contract import (
+    HookInvocationRequest,
+    HookInvocationResult,
+    PreCompactSubject,
+    _json_bytes,
+    validate_hook_result,
+)
+from .state import Contract, RunPhase, RunSnapshot, move
+from .transitions import finish, prepare_effect
+
+if TYPE_CHECKING:
+    from .ports import RunConfiguration
+
+
+class PreCompactHookState(Contract):
+    goal_revision: int = Field(strict=True, ge=0)
+    source_context_digest: str = Field(pattern=r"^[0-9a-f]{64}$")
+    model_cursor: int = Field(strict=True, ge=0)
+    next_hook_index: int = Field(default=0, strict=True, ge=0)
+    replan: bool = False
+    feedback: tuple[dict[str, JsonValue], ...] = ()
+
+
+def precompact_hook_state(snapshot: RunSnapshot) -> PreCompactHookState | None:
+    if snapshot.precompact_hook_state is None:
+        return None
+    value = PreCompactHookState.model_validate_json(_json_bytes(snapshot.precompact_hook_state))
+    return value if value.goal_revision == snapshot.goal_revision else None
+
+
+def planned_precompact_state(
+    snapshot: RunSnapshot, config: RunConfiguration, request: CompactionRequest,
+):
+    hooks = tuple(item for item in config.hooks if "PreCompact" in item.events)
+    if not hooks:
+        return None
+    previous = precompact_hook_state(snapshot)
+    if previous and previous.replan and previous.model_cursor == snapshot.model_calls:
+        return previous.model_copy(update={
+            "source_context_digest": request.source_context_digest, "replan": False,
+        }).model_dump(mode="json")
+    return PreCompactHookState(
+        goal_revision=snapshot.goal_revision, source_context_digest=request.source_context_digest,
+        model_cursor=snapshot.model_calls,
+    ).model_dump(mode="json")
+
+
+def precompact_feedback_messages(
+    snapshot: RunSnapshot, messages: tuple[dict, ...],
+) -> tuple[dict, ...]:
+    current = precompact_hook_state(snapshot)
+    if current is None:
+        return messages
+    seen = {item.get("hook_operation_key") for item in messages}
+    return (*messages, *(item for item in current.feedback
+                         if item["hook_operation_key"] not in seen))
+
+
+def precompact_feedback_keys(snapshot: RunSnapshot) -> tuple[str, ...]:
+    current = precompact_hook_state(snapshot)
+    return tuple(item["hook_operation_key"] for item in current.feedback) if current else ()
+
+
+def precompact_hook_request(
+    snapshot: RunSnapshot, config: RunConfiguration, operation_key: str,
+) -> HookInvocationRequest:
+    current = precompact_hook_state(snapshot)
+    if (snapshot.phase != RunPhase.COMPACTING or current is None
+            or snapshot.compaction_request is None):
+        raise ValueError("PreCompact requires current compaction admission")
+    compact = CompactionRequest.model_validate(snapshot.compaction_request)
+    prefix = snapshot.messages[:compact.source_message_count]
+    if (compact.source_context_digest != current.source_context_digest
+            or source_context_digest(prefix) != compact.source_context_digest):
+        raise ValueError("PreCompact source changed after planning")
+    hooks = tuple(item for item in config.hooks if "PreCompact" in item.events)
+    if current.next_hook_index >= len(hooks):
+        raise ValueError("no pending PreCompact Hook")
+    retained = set(compact.retained_message_refs)
+    # After an earlier compaction old_messages describes the active subset,
+    # while the source digest covers the immutable full transcript prefix.
+    # Preserve original refs; positions in those two lists are not equivalent.
+    original = dict(zip(_refs(prefix), prefix, strict=True))
+    removed = tuple((item.message_id, original[item.message_id])
+                    for item in compact.old_messages if item.message_id not in retained)
+    projection = hooks[current.next_hook_index].compaction_source_projection
+    if projection == "canonical_user":
+        removed = tuple((ref, raw) for ref, raw in removed
+                        if raw.get("role") == "user" and raw.get("kind") is None)
+    return HookInvocationRequest(
+        scope=snapshot.scope, run_id=snapshot.run_id, session_id=snapshot.session_id,
+        turn_id=snapshot.turn_id, operation_key=operation_key,
+        goal_revision=snapshot.goal_revision, goal=snapshot.goal,
+        tool_call_count=snapshot.tool_calls, stop_continuation_count=0,
+        event="PreCompact", definition=hooks[current.next_hook_index],
+        compaction=PreCompactSubject(
+            source_revision=compact.source_revision,
+            source_context_digest=compact.source_context_digest,
+            source_message_count=compact.source_message_count,
+            message_refs=tuple(ref for ref, _ in removed),
+            messages=tuple(raw for _, raw in removed),
+            retained_message_refs=compact.retained_message_refs,
+            source_projection=projection,
+        ),
+    )
+
+
+def prepare_precompact_hook(snapshot: RunSnapshot, config: RunConfiguration):
+    current = precompact_hook_state(snapshot)
+    hooks = tuple(item for item in config.hooks if "PreCompact" in item.events)
+    if current is None or current.next_hook_index >= len(hooks):
+        return None
+    key = f"{snapshot.run_id}:effect:{snapshot.revision + 1}"
+    request = precompact_hook_request(snapshot, config, key)
+    return prepare_effect(snapshot, "hook", {"request": request.model_dump(mode="json")})
+
+
+def reduce_precompact_hook(
+    snapshot: RunSnapshot, config: RunConfiguration, operation_key: str, raw: dict,
+) -> RunSnapshot:
+    request = precompact_hook_request(snapshot, config, operation_key)
+    result = validate_hook_result(request, HookInvocationResult.model_validate(raw))
+    current = precompact_hook_state(snapshot)
+    current = current.model_copy(update={"next_hook_index": current.next_hook_index + 1})
+    updated = snapshot.model_copy(update={"pending_intent": None})
+    if result.status == "uncertain" or result.reason == "binding_unavailable":
+        return finish(updated, "unverified", "effect_outcome_unknown")
+    if result.status == "failed":
+        optional = result.reason in {"producer_failed", "producer_invalid", "producer_timeout",
+                                     "input_budget_exceeded", "output_budget_exceeded"}
+        if not optional or request.definition.failure_mode != "warn":
+            return finish(updated, "blocked", "hook_" + result.reason)
+    else:
+        if result.output.action == "deny":
+            return finish(updated, "blocked", "precompact_hook_denied")
+        if result.output.additional_context:
+            feedback = {
+                "role": "user", "kind": "hook_context", "hook_operation_key": operation_key,
+                "hook_goal_revision": snapshot.goal_revision,
+                "content": json.dumps({
+                    "event": "PreCompact", "hook_id": request.definition.hook_id,
+                    "source_ref": request.definition.source_ref,
+                    "binding_digest": request.definition.binding_digest,
+                    "trust_level": "untrusted", "data": result.output.additional_context,
+                }, ensure_ascii=False, sort_keys=True),
+            }
+            current = current.model_copy(update={"feedback": (*current.feedback, feedback)})
+            updated = updated.model_copy(update={"messages": (*updated.messages, feedback)})
+        if not request.definition.read_only:
+            updated = updated.model_copy(update={"workspace_observation_cursor": None})
+    hooks = tuple(item for item in config.hooks if "PreCompact" in item.events)
+    if current.next_hook_index == len(hooks):
+        current = current.model_copy(update={"replan": True})
+        updated = move(updated, RunPhase.PREPARING_CONTEXT).model_copy(update={
+            "compaction_request": None, "prepared_context": None,
+        })
+    return updated.model_copy(update={"precompact_hook_state": current.model_dump(mode="json")})

ksadk/harness/native/replay_context.py

@@ -0,0 +1,149 @@
+"""Bind private replay to a host-selected message view in the original ledger.
+
+This is an identity for Native's input, not a cryptographic signature check
+or a claim about unobserved provider transformations. Original opaque blocks
+and tool receipts stay immutable. Abandonment is monotonic across replans.
+"""
+
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+import re
+
+from ksadk._model_anthropic import anthropic_content
+from ksadk._model_json import load_model_json
+
+from .context_replay import POLICY, _mark
+from .model import ModelReplayInputContext, ModelReplayMetadata
+from .model_replay import project_model_message
+
+CONTEXT_VERSION = "native-anthropic-input-prefix/v2"
+EDIT_VERSION = "native-model-input-edit/v1"
+
+
+def _digest(value):
+    return hashlib.sha256(json.dumps(value, ensure_ascii=False, sort_keys=True,
+                                     separators=(",", ":"), allow_nan=False).encode()).hexdigest()
+
+
+def replay_identity(replay):
+    return _digest({"profile": replay.profile_digest, "content": replay.anthropic_content_json,
+                    "input_context": replay.input_context.model_dump(mode="json")
+                    if replay.input_context is not None else None})
+
+
+def mark_input_edit(message, original_content, profile, *, source_digest=None):
+    copied = copy.deepcopy(message)
+    if profile is not None and profile.provider_replay_projection_policy == POLICY:
+        copied["model_input_edit"] = {
+            "version": EDIT_VERSION, "profile_digest": profile.digest,
+            "source_content_digest": source_digest or _digest(original_content),
+            "view_content_digest": _digest(copied.get("content")),
+        }
+    return copied
+
+
+def content_digest(content):
+    return _digest(content)
+
+
+def _edited(message, profile):
+    raw = message.get("model_input_edit")
+    if raw is None:
+        return False
+    if (not isinstance(raw, dict)
+            or set(raw) != {"version", "profile_digest", "source_content_digest",
+                            "view_content_digest"}
+            or raw["version"] != EDIT_VERSION or raw["profile_digest"] != profile.digest
+            or raw["view_content_digest"] != _digest(message.get("content"))
+            or not isinstance(raw["source_content_digest"], str)
+            or re.fullmatch(r"[0-9a-f]{64}", raw["source_content_digest"]) is None):
+        raise ValueError("model_input_edit_mismatch")
+    return True
+
+
+def _prefix_part(source, profile, identities):
+    """Normalize host aliases back to original provider IDs, excluding thinking."""
+    message = project_model_message(source, profile)
+    original = source.get("provider_replay")
+    if source.get("role") == "assistant" and original is not None:
+        replay = ModelReplayMetadata.model_validate(original)
+        if replay.profile_digest == profile.digest and replay.anthropic_content_json is not None:
+            blocks = anthropic_content(load_model_json(replay.anthropic_content_json))
+            mapped = dict(replay.anthropic_tool_id_map)
+            for block in blocks:
+                if block["type"] == "tool_use":
+                    identities[mapped.get(block["id"], block["id"])] = block["id"]
+            return {"role": "assistant", "content": [
+                b for b in blocks if b["type"] not in {"thinking", "redacted_thinking"}
+            ]}
+    message.pop("anthropic_content", None)
+    message.pop("anthropic_tool_id_map", None)
+    message.pop("reasoning_content", None)
+    if message.get("role") == "tool":
+        call = message.get("tool_call_id")
+        message["tool_call_id"] = identities.get(call, call)
+    return message
+
+
+def message_prefix_digest(messages, profile):
+    identities = {}
+    return _digest([_prefix_part(m, profile, identities) for m in messages])
+
+
+def request_header_digest(instructions, tools, profile):
+    if profile is None or profile.provider_replay_projection_policy != POLICY:
+        return None
+    # Only model-visible declarations. Host permissions, admission choices,
+    # purpose, request IDs and output budgets are not signed prefix fields.
+    return _digest({"instructions": instructions,
+                    "tools": [tool.function_schema() for tool in tools]})
+
+
+def bind_replay_input(result, request):
+    replay = result.provider_replay
+    if (request.profile.provider_replay_projection_policy != POLICY or replay is None
+            or replay.anthropic_content_json is None):
+        return result
+    bound = replay.model_copy(update={"input_context": ModelReplayInputContext(
+        version=CONTEXT_VERSION,
+        messages_digest=message_prefix_digest(request.messages, request.profile),
+        header_digest=request_header_digest(request.instructions, request.tools, request.profile),
+    )})
+    return result.model_copy(update={"provider_replay": bound})
+
+
+def project_replay_context(messages, profile, *, abandoned=(), header_digest=None):
+    if profile is None or profile.provider_replay_projection_policy != POLICY:
+        return copy.deepcopy(messages), ()
+    discarded = set(abandoned)
+    prefix, identities, output = [], {}, []
+    edited = False
+    for index, source in enumerate(messages):
+        edited = _edited(source, profile) or edited
+        message = copy.deepcopy(source)
+        original = source.get("provider_replay")
+        if source.get("role") == "assistant" and original is not None:
+            replay = ModelReplayMetadata.model_validate(original)
+            if (replay.profile_digest == profile.digest
+                    and replay.anthropic_content_json is not None):
+                blocks = anthropic_content(load_model_json(replay.anthropic_content_json))
+                if any(b["type"] in {"thinking", "redacted_thinking"} for b in blocks):
+                    key = replay_identity(replay)
+                    current = _digest(prefix)
+                    mismatch = (replay.input_context.messages_digest != current
+                                if replay.input_context is not None else edited)
+                    if header_digest is not None and replay.input_context is not None:
+                        # v1 records cannot establish an unchanged header. Do
+                        # not infer one from the current request or rewrite the
+                        # old record as v2; active Runs pin this algorithm.
+                        mismatch = mismatch or replay.input_context.header_digest != header_digest
+                    if (key in discarded or mismatch
+                            or source.get("provider_replay_projection") is not None):
+                        discarded.add(key)
+                        message = _mark(source, f"request-message:{index}", current)
+        output.append(message)
+        prefix.append(_prefix_part(message, profile, identities))
+    return tuple(output), tuple(sorted(discarded))

ksadk/harness/native/request_media.py

@@ -0,0 +1,112 @@
+"""Pure, profile-bound inline media projection before origin metadata is lost.
+
+This counts encoded data URLs, not tokens, remote resource sizes or the full
+wire body. Canonical receipts/source coverage remain untouched. Only the
+current dispatch view may omit already observed historical media.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Literal
+
+from pydantic import Field
+
+from .context_history import _content_blocks, text_only_tool_message
+from .model import ModelProfile
+from .state import Contract
+from .tool_observation import model_observation_messages
+
+
+class RequestMediaError(ValueError):
+    """A known preflight refusal; no model request has been dispatched."""
+
+
+class ModelRequestDispatchDenial(Contract):
+    schema_version: Literal["ksadk.native-model-request-denial/v1"] = (
+        "ksadk.native-model-request-denial/v1"
+    )
+    operation_key: str = Field(min_length=1)
+    reason: Literal["request_current_media_over_budget"] = "request_current_media_over_budget"
+
+
+def _omitted(block):
+    digest = hashlib.sha256(json.dumps(
+        block, ensure_ascii=False, sort_keys=True, separators=(",", ":")
+    ).encode()).hexdigest()
+    return {"type": "text", "text": json.dumps({
+        "type": "ksadk.request-media-omission/v1",
+        "media_digest": digest,
+        "status": "not_sent_in_this_request",
+        "reason": "inline_image_budget",
+        "observation": (
+            "Historical image omitted from this model request. Use the textual receipt; "
+            "do not claim to have seen the image or repeat already executed side effects "
+            "solely because its pixels were omitted."
+        ),
+    }, ensure_ascii=False, sort_keys=True)}
+
+
+def project_request_media(messages, profile: ModelProfile | None, *, purpose="task"):
+    if profile is None or profile.request_media_policy is None:
+        # Legacy profiles retain their serialization and request semantics.
+        return tuple(json.loads(json.dumps(message, ensure_ascii=False)) for message in messages)
+    copied = model_observation_messages(messages)
+    from .replay_context import content_digest
+
+    original_digests = tuple(content_digest(m.get("content")) for m in copied)
+    actual_user = -1
+    if purpose == "task":
+        actual_user = next((i for i in range(len(copied) - 1, -1, -1)
+                            if copied[i].get("role") == "user"
+                            and copied[i].get("kind") is None), -1)
+    effective = []
+    media = []
+    for i, message in enumerate(copied):
+        # Validate before omission; a zero budget cannot legitimize bad media.
+        blocks = _content_blocks(message)
+        has_image = any(block["type"] == "image_url" for block in blocks)
+        if has_image and message.get("role") not in {"user", "tool"}:
+            raise ValueError("image observations require user or tool content")
+        if has_image and profile.image_input_mode == "text_only":
+            if message.get("role") != "tool":
+                raise ValueError("model profile does not accept user image input")
+            message = text_only_tool_message(message)
+            blocks = ()
+        effective.append(message)
+        for j, block in enumerate(blocks):
+            if block["type"] == "image_url" and block["image_url"]["url"].startswith("data:"):
+                media.append((i, j, len(block["image_url"]["url"].encode("utf-8"))))
+    limit = profile.request_media_policy.max_inline_image_bytes
+    if sum(size for _, _, size in media) <= limit:
+        return _edited_media(original_digests, effective, profile)
+    protected = {(i, j) for i, j, _ in media if i == actual_user}
+    remaining = limit - sum(size for i, _, size in media if i == actual_user)
+    if remaining < 0:
+        raise RequestMediaError("request_current_media_over_budget")
+    retained = set(protected)
+    for i, j, size in reversed(media):
+        if (i, j) in protected or size > remaining:
+            continue
+        retained.add((i, j))
+        remaining -= size
+    for i, j, _ in media:
+        if (i, j) not in retained:
+            effective[i]["content"][j] = _omitted(effective[i]["content"][j])
+    for message in effective:
+        content = message.get("content")
+        if (message.get("role") == "tool" and isinstance(content, list)
+                and not any(block["type"] == "image_url" for block in content)):
+            message["content"] = "\n".join(block["text"] for block in content)
+    return _edited_media(original_digests, effective, profile)
+
+
+def _edited_media(originals, effective, profile):
+    from .replay_context import content_digest, mark_input_edit
+
+    return tuple(
+        mark_input_edit(message, None, profile, source_digest=original)
+        if content_digest(message.get("content")) != original else message
+        for original, message in zip(originals, effective)
+    )

ksadk/harness/native/restore_contract.py

@@ -0,0 +1,16 @@
+"""Reader provenance is diagnostic data, never a second execution checkpoint."""
+
+from pydantic import Field
+
+from .state import Contract
+
+SNAPSHOT_READER_VERSION = "ksadk.native-snapshot-reader/v1"
+
+
+class StoreRestoreAudit(Contract):
+    reader_version: str = Field(min_length=1, max_length=160)
+    snapshot_schema_version: str = Field(min_length=1, max_length=160)
+    configuration_digest: str
+    fencing_token: int | None = Field(default=None, strict=True, ge=1)
+    executed_migration_ids: tuple[str, ...] = ()
+    historical_migration_ids: tuple[str, ...] = ()

ksadk/harness/native/run_clock.py

@@ -0,0 +1,120 @@
+"""Account active execution in the ledger; stop before another expired effect."""
+
+from __future__ import annotations
+
+import hashlib
+from time import monotonic
+
+from ksadk.harness.stores.native_contract import RunStore
+
+from .model_recovery_contract import RunClockQuote as RunClockQuote
+from .model_recovery_contract import unavailable_uncertain_usage
+from .state import CommitBatch, EffectReceipt, RunPhase, RunScope, RunSnapshot
+from .tool_interruption import record_tool_interruption
+from .transitions import commit_transition, finish
+
+
+class ActiveRunClock:
+    """Local monotonic intervals advance a persisted consumed-time counter.
+
+    Host ports own cleanup. A lost running intent remains uncertain after
+    attach; this clock does not claim to reconstruct unrecorded crash time.
+    """
+
+    def __init__(self, limit: float | None) -> None:
+        self.limit = limit
+        self.anchors: dict[str, float] = {}
+
+    @staticmethod
+    def active(snapshot: RunSnapshot) -> bool:
+        return not snapshot.phase.terminal and snapshot.phase not in {
+            RunPhase.PAUSED, RunPhase.AWAITING_INTERACTION,
+        }
+
+    def attach(self, snapshot: RunSnapshot) -> None:
+        if self.limit is not None and self.active(snapshot):
+            self.anchors.setdefault(snapshot.run_id, monotonic())
+
+    def release(self, run_id: str) -> None:
+        self.anchors.pop(run_id, None)
+
+    def elapsed(self, snapshot: RunSnapshot, now: float | None = None) -> float:
+        anchor = self.anchors.get(snapshot.run_id)
+        now = monotonic() if now is None else now
+        return snapshot.execution_elapsed_seconds + (
+            max(0, now - anchor) if anchor is not None else 0
+        )
+
+    def quote(self, snapshot: RunSnapshot, *, wall_time: float,
+              clock_domain_digest: str) -> RunClockQuote:
+        now = monotonic()
+        return RunClockQuote(
+            source_snapshot_digest=hashlib.sha256(snapshot.model_dump_json().encode()).hexdigest(),
+            measured_elapsed_seconds=self.elapsed(snapshot, now),
+            monotonic_seconds=now, wall_time=float(wall_time),
+            clock_domain_digest=clock_domain_digest,
+        )
+
+    def remaining(self, snapshot: RunSnapshot) -> float | None:
+        return (
+            None if self.limit is None else
+            self.limit - self.elapsed(snapshot) - snapshot.model_recovery_debt_seconds
+        )
+
+    def prepare_commit(
+        self, previous: RunSnapshot, batch: CommitBatch,
+    ) -> tuple[CommitBatch, float]:
+        now = monotonic()
+        if self.limit is not None:
+            batch = batch.model_copy(update={"snapshot": batch.snapshot.model_copy(update={
+                "execution_elapsed_seconds": self.elapsed(previous, now),
+            })})
+        return batch, now
+
+    def committed(self, snapshot: RunSnapshot, now: float) -> None:
+        if self.limit is not None and self.active(snapshot):
+            self.anchors[snapshot.run_id] = now
+        else:
+            self.release(snapshot.run_id)
+
+
+def wall_budget_stop(
+    snapshot: RunSnapshot, store: RunStore, scope: RunScope, *, elapsed: float,
+) -> CommitBatch:
+    """Retain an undispatched/unknown pending receipt before a budget terminal."""
+    updated = finish(snapshot, "budget_exhausted", "wall_time_hard_limit")
+    receipts, extra = (), ()
+    intent, receipt = None, None
+    if snapshot.pending_intent:
+        intent = store.get_intent(scope, snapshot.run_id, snapshot.pending_intent)
+        existing = store.get_receipt(scope, snapshot.run_id, snapshot.pending_intent)
+        receipt = existing
+        if intent is not None and existing is None:
+            running = intent.status == "running"
+            if running:
+                # The deadline proves elapsed time, not what a lost effect did.
+                updated = finish(snapshot, "unverified", "effect_outcome_unknown")
+            receipt = EffectReceipt(
+                operation_key=intent.operation_key,
+                status="uncertain" if running else "failed",
+                result={"reason": "effect_outcome_unknown" if running else "not_dispatched",
+                        "deadline_cause": "wall_time_hard_limit"},
+            )
+            receipts = (receipt,)
+            extra = (("effect.received", {"operation_key": intent.operation_key,
+                      "kind": intent.kind, "status": receipt.status}),)
+            if running and intent.kind in {"model", "tool"}:
+                counter = "model_calls" if intent.kind == "model" else "tool_calls"
+                updated = updated.model_copy(update={
+                    counter: getattr(snapshot, counter) + intent.loop_attempts,
+                })
+            if running and intent.kind == "model":
+                extra = (*extra, unavailable_uncertain_usage(intent.operation_key))
+    batch = commit_transition(
+        snapshot, updated, "budget.exhausted",
+        {"reason": "wall_time_hard_limit", "execution_elapsed_seconds": elapsed,
+         **({"model_recovery_debt_seconds": snapshot.model_recovery_debt_seconds}
+            if snapshot.model_recovery_debt_seconds else {})},
+        receipts=receipts, extra_events=extra,
+    )
+    return record_tool_interruption(snapshot, batch, intent, receipt)