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

ksadk/harness/native/model_recovery_contract.py

@@ -0,0 +1,35 @@
+"""Pure recovery clock and unknown-usage data; no clocks, stores or exchange."""
+
+from __future__ import annotations
+
+from pydantic import Field
+
+from .state import Contract
+
+
+class RunClockQuote(Contract):
+    source_snapshot_digest: str
+    measured_elapsed_seconds: float = Field(strict=True, ge=0, allow_inf_nan=False)
+    monotonic_seconds: float = Field(strict=True, ge=0, allow_inf_nan=False)
+    wall_time: float = Field(strict=True, ge=0, allow_inf_nan=False)
+    clock_domain_digest: str = Field(pattern=r"^[0-9a-f]{64}$")
+
+
+def unavailable_uncertain_usage(operation_key: str) -> tuple[str, dict[str, str]]:
+    return unavailable_model_usage(
+        operation_key, f"{operation_key}:unsealed", "model_effect_uncertain"
+    )
+
+
+def unavailable_model_usage(
+    request_id: str, attempt_id: str, source: str
+) -> tuple[str, dict[str, str]]:
+    return (
+        "usage.unavailable",
+        {
+            "semantics": "delta",
+            "request_id": request_id,
+            "attempt_id": attempt_id,
+            "source": source,
+        },
+    )

ksadk/harness/native/model_replay.py

@@ -0,0 +1,128 @@
+"""Private model protocol projection; no I/O, task verdicts or public text."""
+from __future__ import annotations
+
+import copy
+import json
+
+from ksadk._model_anthropic import anthropic_content, anthropic_projection
+from ksadk._model_json import load_model_json
+
+from .model import ModelProfile, ModelReplayMetadata, ModelTurnResult
+
+
+def replay_binding_failure(
+    profile: ModelProfile, replay: ModelReplayMetadata | None, *, required: bool
+) -> str | None:
+    if profile.provider_replay_mode != "none" and required and replay is None:
+        return "model_replay_unavailable"
+    if replay is not None and (
+        profile.provider_replay_mode == "none" or replay.profile_digest != profile.digest
+        or (profile.provider_replay_mode == "anthropic_content")
+        != (replay.anthropic_content_json is not None)
+    ):
+        return "model_replay_profile_mismatch"
+    return None
+
+
+def seal_model_replay(
+    result: ModelTurnResult, profile: ModelProfile, reasoning_content: str
+) -> ModelTurnResult:
+    if profile.provider_replay_mode != "reasoning_content" or result.response_kind not in {
+        "tool_calls", "final_candidate", "output_limit",
+    }:
+        return result
+    replay = ModelReplayMetadata(
+        profile_digest=profile.digest, reasoning_content=reasoning_content
+    )
+    return ModelTurnResult.model_validate({
+        **result.model_dump(), "provider_replay": replay.model_dump(),
+    })
+
+
+def seal_anthropic_replay(
+    result: ModelTurnResult, profile: ModelProfile, content: object,
+) -> ModelTurnResult:
+    if profile.provider_replay_mode != "anthropic_content" or result.response_kind not in {
+        "tool_calls", "final_candidate", "output_limit",
+    }:
+        return result
+    blocks = anthropic_content(content)
+    replay = ModelReplayMetadata(
+        version="model-replay/v2", profile_digest=profile.digest, reasoning_content="",
+        anthropic_content_json=json.dumps(blocks, ensure_ascii=False, allow_nan=False,
+                                          separators=(",", ":")),
+    )
+    return ModelTurnResult.model_validate({
+        **result.model_dump(), "provider_replay": replay.model_dump(),
+    })
+
+
+def replay_fields(replay: ModelReplayMetadata | None) -> dict:
+    return {"provider_replay": replay.model_dump(mode="json")} if replay is not None else {}
+
+
+def remap_anthropic_replay(
+    replay: ModelReplayMetadata | None, identities: dict[str, str],
+) -> ModelReplayMetadata | None:
+    if replay is None or replay.anthropic_content_json is None:
+        return replay
+    _, calls = anthropic_projection(load_model_json(replay.anthropic_content_json))
+    previous = dict(replay.anthropic_tool_id_map)
+    pairs = []
+    for call in calls:
+        original = call["call_id"]
+        current = previous.get(original, original)
+        projected = identities.get(current, current)
+        if projected != original:
+            pairs.append((original, projected))
+    return ModelReplayMetadata.model_validate({
+        **replay.model_dump(), "anthropic_tool_id_map": tuple(pairs),
+    })
+
+
+def project_model_replay(source: dict, profile: ModelProfile) -> dict:
+    if profile.provider_replay_mode == "none" or source.get("provider_replay") is None:
+        return {}
+    replay = ModelReplayMetadata.model_validate(source["provider_replay"])
+    # A new Build/model may inherit visible history. Private protocol material
+    # from a different pinned profile does not cross that boundary.
+    if replay.profile_digest != profile.digest:
+        return {}
+    if profile.provider_replay_mode == "anthropic_content":
+        if replay.anthropic_content_json is None:
+            raise ValueError("original Anthropic replay unavailable")
+        from .context_replay import replay_content_view
+
+        return {
+            "anthropic_content": replay_content_view(source, profile, replay),
+            "anthropic_tool_id_map": [list(pair) for pair in replay.anthropic_tool_id_map],
+        }
+    if replay.anthropic_content_json is not None:
+        raise ValueError("Anthropic replay cannot cross a Chat profile")
+    return {"reasoning_content": replay.reasoning_content}
+
+
+def project_model_message(source: dict, profile: ModelProfile) -> dict:
+    """Detach provider message fields from canonical host provenance.
+
+    Both admission counters and model adapters consume this projection. Audit
+    IDs and artifact metadata remain in the ledger; private replay only crosses
+    the exact pinned profile. Tool content is never interpreted as provenance.
+    Media content stays typed for the adapter's separate framing and budget.
+    """
+    if source.get("operator_history_projection") is not None:
+        from .context_replay import steered_operator_view
+
+        return steered_operator_view(source, profile)
+    role = source.get("role")
+    if role not in {"system", "developer", "user", "assistant", "tool"}:
+        raise ValueError("unsupported canonical message role")
+    fields = {"role", "content", "name"}
+    if role == "assistant":
+        fields.add("tool_calls")
+    elif role == "tool":
+        fields.add("tool_call_id")
+    message = copy.deepcopy({key: value for key, value in source.items() if key in fields})
+    if role == "assistant":
+        message.update(project_model_replay(source, profile))
+    return message

ksadk/harness/native/model_request.py

@@ -0,0 +1,133 @@
+"""One pure model-request constructor for preparation, dispatch and sealing."""
+
+from .context_runtime_contracts import CompactionRequest
+from .delivery_review import delivery_review_messages
+from .operator_guidance import operator_input_history_view
+from .ports import ModelRequest
+from .request_media import project_request_media
+from .stop_hook_runtime import hook_feedback_messages
+from .tool_budget import (
+    has_admitted_task_tools,
+    model_instructions,
+    model_tool_catalog,
+    model_turn_control,
+    tools_exhausted,
+)
+from .tool_hook_runtime import tool_hook_feedback_messages
+from .tool_observation import model_observation_messages
+from .turn_control import ModelTurnControl
+
+
+def model_request(snapshot, config, *, key, payload):
+    summary = payload.get("purpose") == "compaction"
+    review = payload.get("purpose") == "delivery_review"
+    context = snapshot.prepared_context or {}
+    compact = CompactionRequest.model_validate(snapshot.compaction_request) if summary else None
+    control = None if summary or review else model_turn_control(snapshot, config)
+    captured_control = payload.get("turn_control")
+    if (
+        not summary
+        and not review
+        and isinstance(captured_control, dict)
+        and captured_control.get("reason") == "task_tools_exhausted"
+        and not has_admitted_task_tools(config)
+        and tools_exhausted(snapshot, config)
+    ):
+        # Older ready intents classified an empty tool surface as spent
+        # budget. Keep that committed, non-authorizing control for this
+        # effect only; new turns use the corrected admission projection.
+        control = ModelTurnControl.model_validate(captured_control)
+    if context and not summary and not review:
+        captured = context.get("turn_control")
+        prepared_control = ModelTurnControl.model_validate(captured) if captured else None
+        if prepared_control != control:
+            raise ValueError("prepared model-turn control differs from current admission")
+    request = ModelRequest(
+        scope=snapshot.scope,
+        run_id=snapshot.run_id,
+        request_id=key,
+        attempt_id=f"{key}:attempt:1",
+        profile=compact.profile if compact else config.profile,
+        purpose="compaction" if summary else "delivery_review" if review else "task",
+        max_output_tokens=compact.summary_output_tokens if compact else None,
+        instructions=(
+            compact.summary_instructions
+            if compact
+            else context.get("instructions", (
+                config.instructions
+                if config.profile.operator_guidance_policy == "journaled-system/v1"
+                else model_instructions(snapshot, config)
+            ))
+        ),
+        messages=(
+            compact.summary_messages
+            if compact
+            else model_observation_messages(
+                context.get("messages", tool_hook_feedback_messages(
+                    snapshot, hook_feedback_messages(
+                        snapshot, delivery_review_messages(snapshot)
+                    )
+                ))
+            )
+        ),
+        tools=() if summary else model_tool_catalog(snapshot, config),
+        turn_control=control,
+    )
+    request = request.model_copy(update={"messages": operator_input_history_view(
+        request.messages, request.profile
+    )})
+    request = request.model_copy(update={"messages": project_request_media(
+        request.messages, request.profile, purpose=request.purpose
+    )})
+    from .replay_context import project_replay_context, request_header_digest
+
+    if request.purpose != "compaction":
+        messages, _ = project_replay_context(
+            request.messages, request.profile,
+            abandoned=snapshot.compaction_history.get("abandoned_replay_digests", ()),
+            header_digest=request_header_digest(
+                request.instructions, request.tools, request.profile),
+        )
+        request = request.model_copy(update={"messages": messages})
+    return request
+
+
+def capture_request_context(snapshot, batch, config):
+    """Commit the same selected view before dispatch, including failed/canceled attempts."""
+    from .context_replay import POLICY
+    from .replay_context import project_replay_context, request_header_digest
+    from .request_media import RequestMediaError
+    from .transitions import commit_transition, finish
+
+    if config.profile.provider_replay_projection_policy != POLICY:
+        return batch
+    intent = batch.intents[0]
+    try:
+        request = model_request(batch.snapshot, config, key=intent.operation_key,
+                                payload=intent.payload)
+        messages, discarded = project_replay_context(
+            request.messages, config.profile,
+            abandoned=snapshot.compaction_history.get("abandoned_replay_digests", ()),
+            header_digest=request_header_digest(
+                request.instructions, request.tools, request.profile),
+        )
+    except RequestMediaError:
+        return batch  # The existing zero-dispatch denial path consumes the original intent.
+    except (TypeError, ValueError):
+        return commit_transition(
+            snapshot, finish(snapshot, "blocked", "model_replay_context_invalid"),
+            "context.blocked", {"reason": "model_replay_context_invalid"},
+        )
+    context = {**(batch.snapshot.prepared_context or {}),
+               "instructions": request.instructions, "messages": list(messages),
+               "replay_header_digest": request_header_digest(
+                   request.instructions, request.tools, request.profile),
+               "turn_control": request.turn_control.model_dump(mode="json")
+               if request.turn_control is not None else None}
+    history = dict(batch.snapshot.compaction_history)
+    if discarded:
+        history["abandoned_replay_digests"] = list(discarded)
+    updated = batch.snapshot.model_copy(update={
+        "prepared_context": context, "compaction_history": history,
+    })
+    return batch.model_copy(update={"snapshot": updated})

ksadk/harness/native/model_runtime.py

@@ -0,0 +1,196 @@
+"""Model exchanges: provisional stream events and bounded persistent retry policy."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from ksadk._async_iterators import close_async_iterator
+
+from .model import ModelStreamEvent, ModelTurnResult
+from .model_input import input_binding_failure, input_event, observe_input
+from .model_recovery_contract import unavailable_model_usage
+from .model_recovery_contract import unavailable_uncertain_usage as unavailable_uncertain_usage
+from .ports import ModelPort, ModelRequest, RunConfiguration
+from .state import CommitBatch, EffectIntent, EffectReceipt, RunPhase, RunSnapshot, move
+from .transitions import commit_transition
+
+
+async def exchange(
+    model: ModelPort, request: ModelRequest, emit: Callable[[ModelStreamEvent], None] | None = None
+) -> ModelTurnResult:
+    if request.profile.streaming:
+        stream = getattr(model, "stream", None)
+        if not callable(stream):
+            raise ValueError("pinned streaming profile requires a stream-capable model port")
+        sealed = None
+        input_receipt = None
+        seq = 0
+        iterator = stream(request.model_copy(deep=True))
+        try:
+            async for raw in iterator:
+                event = ModelStreamEvent.model_validate_json(raw.model_dump_json())
+                if (
+                    event.request_id != request.request_id
+                    or event.attempt_id != request.attempt_id
+                    or event.seq != seq + 1
+                    or sealed is not None
+                ):
+                    raise ValueError("model stream identity or order mismatch")
+                seq = event.seq
+                if event.kind == "input_metadata":
+                    if input_binding_failure(request.profile, event.input_receipt):
+                        raise ValueError("model stream input profile mismatch")
+                    input_receipt = event.input_receipt
+                if event.kind == "final":
+                    sealed = event.result
+                    if input_receipt is not None and sealed.input_receipt != input_receipt:
+                        raise ValueError("sealed input receipt conflicts with observed input")
+                elif emit is not None:
+                    emit(event)
+        finally:
+            await close_async_iterator(iterator, owner="native_model")
+        if sealed is None:
+            raise ValueError("model stream ended without a sealed result")
+        result = sealed
+    else:
+        result = await model.complete(request.model_copy(deep=True))
+    result = ModelTurnResult.model_validate_json(result.model_dump_json())
+    if result.request_id != request.request_id or result.attempt_id != request.attempt_id:
+        raise ValueError("model request identity mismatch")
+    if input_binding_failure(request.profile, result.input_receipt):
+        raise ValueError("model result input profile mismatch")
+    return result
+
+
+def provisional_delta(snapshot: RunSnapshot, event: ModelStreamEvent) -> CommitBatch:
+    """Record a streamed delta without promoting it to an accepted answer."""
+    if snapshot.pending_intent != event.request_id:
+        raise ValueError("delta no longer belongs to the active request")
+    if event.kind == "input_metadata":
+        return commit_transition(snapshot, observe_input(snapshot, event.input_receipt),
+                                 *input_event(event.input_receipt))
+    if event.kind == "public_summary":
+        from ksadk.harness.tool_display import display_text
+
+        return commit_transition(snapshot, snapshot, "thinking.summary.delta", {
+            "text": display_text(event.text), "request_id": event.request_id,
+            "attempt_id": event.attempt_id, "stream_seq": event.seq,
+        })
+    if event.kind != "text_delta":
+        raise ValueError("sealed result is not a provisional observation")
+    return commit_transition(
+        snapshot,
+        snapshot,
+        "text.delta",
+        {
+            "text": event.text,
+            "phase": "provisional",
+            "request_id": event.request_id,
+            "attempt_id": event.attempt_id,
+            "stream_seq": event.seq,
+        },
+    )
+
+
+def retry_delay(
+    result: ModelTurnResult, consecutive_errors: int, config: RunConfiguration
+) -> float:
+    if result.response_kind not in {
+        "provider_retryable_error",
+        "empty_response",
+        "malformed_tool_call",
+    }:
+        return 0.0
+    profile = config.profile
+    cap = min(profile.retry_max_delay_seconds, 60.0)
+    delay = profile.retry_initial_delay_seconds
+    # Saturate rather than exponentiating untrusted or very large counters.
+    for _ in range(min(max(0, consecutive_errors - 1), 128)):
+        delay = min(cap, delay * profile.retry_backoff_multiplier)
+        if delay >= cap:
+            break
+    if result.failure_kind == "rate_limit":
+        if result.retry_after_seconds is not None:
+            # A provider's explicit quota deadline takes precedence over the
+            # short transport backoff, but remains bounded in this process.
+            return min(300.0, max(delay, result.retry_after_seconds))
+        return max(delay, profile.rate_limit_cooldown_seconds)
+    return min(cap, max(delay, result.retry_after_seconds or 0.0))
+
+
+def recover_timed_out_model(
+    snapshot: RunSnapshot, config: RunConfiguration, operation_key: str, *, now: float
+) -> RunSnapshot:
+    """Retire a joined in-process model timeout through the bounded retry path.
+
+    The caller retains the uncertain receipt and reports unknown usage. A lost
+    running intent after process takeover never enters this path.
+    """
+    from .machine import reduce_model
+
+    result = ModelTurnResult(
+        response_kind="provider_retryable_error",
+        request_id=operation_key,
+        attempt_id=f"{operation_key}:attempt:1",
+    )
+    updated = reduce_model(snapshot, result, config)
+    delay = retry_delay(result, updated.provider_errors, config)
+    return updated.model_copy(update={"retry_not_before": now + delay if delay else 0})
+
+
+def recover_unsealed_model_receipt(
+    snapshot: RunSnapshot,
+    intent: EffectIntent,
+    receipt: EffectReceipt,
+    config: RunConfiguration,
+    *,
+    now: float,
+) -> tuple[RunSnapshot, tuple[str, dict[str, str]]] | None:
+    """Settle joined model attempts without treating them as sealed answers.
+
+    This is only for a known in-process timeout or an active pause. A lost
+    running intent after takeover and every tool effect remain unreplayable.
+    """
+    if intent.kind != "model":
+        return None
+    key = intent.operation_key
+    if (
+        receipt.status == "uncertain"
+        and intent.payload.get("purpose") != "compaction"
+        and receipt.result == {"reason": "effect_timeout"}
+    ):
+        return recover_timed_out_model(snapshot, config, key, now=now), unavailable_timeout_usage(
+            key
+        )
+    if receipt.status != "failed" or receipt.result != {"reason": "model_paused_before_result"}:
+        return None
+    updated = snapshot.model_copy(
+        update={"pending_intent": None, "model_calls": snapshot.model_calls + 1}
+    )
+    if intent.payload.get("purpose") != "compaction":
+        updated = move(updated, RunPhase.PREPARING_CONTEXT)
+    return updated, unavailable_model_usage(key, f"{key}:attempt:1", "model_paused")
+
+
+def unavailable_timeout_usage(operation_key: str) -> tuple[str, dict[str, str]]:
+    # A canceled model request can still incur provider charges. Never report
+    # zero tokens merely because it produced no sealed ModelTurnResult.
+    return unavailable_model_usage(
+        operation_key, f"{operation_key}:attempt:1", "model_effect_timeout"
+    )
+
+
+def sealed_model_usage_event(result: ModelTurnResult) -> tuple[str, dict]:
+    if result.usage is None:
+        return unavailable_model_usage(
+            result.request_id, result.attempt_id, "provider_usage_missing"
+        )
+    return (
+        "usage.reported",
+        {
+            "semantics": "delta",
+            "request_id": result.request_id,
+            "attempt_id": result.attempt_id,
+            **result.usage.model_dump(mode="json"),
+        },
+    )