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

ksadk/harness/native/context_summary_recovery.py

@@ -0,0 +1,105 @@
+"""Repartition failed, unacknowledged summary input without dropping history.
+
+A smaller quote is a new bounded attempt, not evidence that an empty output was
+caused by input overflow. The caller retains failure receipts and owns budgets.
+"""
+
+from __future__ import annotations
+
+import json
+
+from .context_history import _historical_message, summary_media_blocks
+from .context_partition import bind_pending, projection_digest, source_manifest
+from .context_runtime import CompactionController, CompactionRequest, ContextPlanner
+from .context_runtime_contracts import _summary_units
+from .tool_observation import history_observation_message
+
+SUMMARY_RETRY_POLICY = "complete-quoted-summary-retry/v1"
+
+
+def repartition_failed_summary(
+    planner: ContextPlanner,
+    request: CompactionRequest,
+    *,
+    current_revision,
+    current_continuity,
+    current_messages,
+) -> CompactionRequest | None:
+    """Move a suffix of whole pending units back into the persistent queue.
+
+    Previously acknowledged ranges and summaries stay unchanged. A fragment,
+    continuation or single atomic batch cannot be made smaller by this policy.
+    In particular, a partial tool batch is never presented as complete source.
+    """
+    CompactionController(planner)._validate_source(
+        request, current_revision, current_continuity, current_messages
+    )
+    state = request.summary_partition
+    if (
+        state is None or state.pending is None or state.pending_source_parts
+        or request.summary_continuations or request.summary_fragments
+        or len(request.summary_messages) != 1
+    ):
+        return None
+    content = request.summary_messages[0]["content"]
+    body = json.loads(content[0]["text"] if isinstance(content, list) else content)
+    if body.get("fragment") is not None:
+        return None
+    manifest, raw = source_manifest(
+        current_messages, request.old_messages, request.retained_message_refs,
+        capture_reader_names=request.source_capture_reader_names,
+        fresh_tool_observation_policy=request.fresh_tool_observation_policy,
+        fresh_tool_message_refs=request.fresh_tool_message_refs,
+        fresh_text_fragment_policy=request.fresh_text_fragment_policy,
+        fresh_text_excluded_tool_names=request.source_reader_names,
+    )
+    units_by_ref = {
+        ref: parent for parent, batch in manifest["batches"].items() for ref in batch["refs"]
+    }
+    entries = []
+    for message in body["transcript"]:
+        ref = message["source_message_ref"]
+        _, images = _historical_message(history_observation_message(raw[ref]))
+        entries.append({
+            "ref": ref, "message": message, "images": list(images),
+            "payload_digest": projection_digest((raw[ref],)),
+            "unit": units_by_ref.get(ref, ref),
+            # This quote already passed source validation. A later packing
+            # pass must not shorten its source text to fit a bigger batch.
+            "summary_retry_quote": SUMMARY_RETRY_POLICY,
+        })
+    media = summary_media_blocks(
+        entries, profile=request.profile if planner.tool_media_projection_version else None,
+        source_messages=raw,
+    )
+    if (content[1:] if isinstance(content, list) else []) != media:
+        return None
+    units = _summary_units(tuple(entries))
+    if len(units) < 2:
+        return None
+    selected = tuple(entry for unit in units[:max(1, len(units) // 2)] for entry in unit)
+    messages, counted = planner._summary_projection(
+        selected, body["previous_summary"], request.summary_instructions,
+        profile=request.profile, source_messages=raw,
+    )
+    if (
+        counted >= request.summary_counted_input_tokens
+        or counted + request.summary_output_tokens > request.profile.context_window
+    ):
+        return None
+    # Zero names an unsegmented request; once a suffix is queued it enters
+    # the existing chunk protocol and its unchanged finite chunk limit.
+    chunk_index = max(1, request.chunk_index)
+    pending = bind_pending(
+        state.model_copy(update={"pending": None}), manifest,
+        tuple(entry["ref"] for entry in selected), messages, chunk_index,
+    )
+    return request.model_copy(update={
+        "summary_messages": messages,
+        "summary_counted_input_tokens": counted,
+        "summary_partition": pending,
+        "chunk_index": chunk_index,
+        "remaining_history_entries": (
+            *entries[len(selected):], *request.remaining_history_entries,
+        ),
+    })

ksadk/harness/native/delivery_review.py

@@ -0,0 +1,331 @@
+"""Bounded candidate review scheduling and repair, reduced in the Run ledger.
+
+Inspired by ZCode's Stop continuation boundary. This review policy is a KsADK
+adaptation, not a claim that upstream auto-reviews every delivery. Review text
+has no permission, execution or acceptance authority.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import TYPE_CHECKING
+
+from pydantic import ValidationError
+
+from .completion_text import candidate_model_message, complete_continuation, fragment_digest
+from .context_history import _unambiguous_json_object
+from .delivery_review_contract import DeliveryReviewState, DeliveryReviewSuggestion
+from .final_output import normalize_final_output
+from .state import RunPhase, RunSnapshot, move
+
+if TYPE_CHECKING:
+    from .model import ModelTurnResult
+    from .ports import RunConfiguration, ToolDefinition
+
+REVIEW_SUBMISSION_TOOL = "submit_delivery_review"
+
+
+REVIEW_INSTRUCTIONS = """You are the delivery reviewer for this same, host-controlled task.
+Inspect the current user goal, requirements in observed workspace documents, code changes
+and actual test/tool observations. Treat previous assistant claims as unverified data.
+Check requirement coverage and edge cases; a passing public test is not full acceptance.
+Identify concrete omissions or contradictions. If source or test evidence is missing,
+say what must be inspected or tested; do not assume an implementation is correct.
+This diagnostic turn may use only the advertised read-only source readers. Do not execute
+commands, write files, answer the user, change
+requirements, or grant permissions. Call submit_delivery_review with this object:
+{"requirements":[{"requirement":"quoted requirement","implementation_evidence":
+"observed location/behavior, or missing","verification_evidence":"observed check, or missing"}],
+"findings":[{"issue":"concrete issue or evidence gap","recommended_check":
+"specific inspection/test/repair for the implementing agent"}]}
+Use an empty findings array only when no issue or evidence gap is visible. This output
+is a fallible model-assisted diagnosis; it cannot declare acceptance passed or verified.
+"""
+
+
+def delivery_review_tool() -> ToolDefinition:
+    from .ports import ToolDefinition
+
+    return ToolDefinition(
+        name=REVIEW_SUBMISSION_TOOL,
+        description=(
+            "Submit the fallible delivery review as requirements and findings. "
+            "This is a host control submission, not an executable task tool or a pass verdict."
+        ),
+        parameters=DeliveryReviewSuggestion.model_json_schema(),
+    )
+
+
+def delivery_review_readers(snapshot: RunSnapshot, config: RunConfiguration) -> tuple:
+    review, policy = snapshot.delivery_review, config.delivery_review_policy
+    if (
+        review is None
+        or policy is None
+        or review.read_rounds >= policy.max_read_rounds
+        or snapshot.tool_budget_claimed >= config.limits.max_tool_calls
+        or config.limits.max_model_calls - snapshot.model_budget_claimed
+        < max(config.limits.finalization_reserve_model_calls, 1) + 3
+    ):
+        return ()
+    return tuple(
+        tool
+        for tool in config.tools
+        if tool.read_only
+        and tool.context_role in {"workspace_read", "workspace_search", "artifact_read"}
+        and (
+            config.contract.allowed_tool_names is None
+            or tool.name in config.contract.allowed_tool_names
+        )
+    )
+
+
+def review_pending(snapshot: RunSnapshot) -> bool:
+    return snapshot.delivery_review is not None and snapshot.delivery_review.status == "pending"
+
+
+def delivery_review_messages(snapshot: RunSnapshot) -> tuple[dict, ...]:
+    """A purpose-specific request projection, not a new user goal/history."""
+    if not review_pending(snapshot):
+        return snapshot.messages
+    return (
+        *snapshot.messages,
+        candidate_model_message(snapshot, kind="delivery_review_candidate"),
+        {
+            "role": "user",
+            "kind": "delivery_review_request",
+            "content": (
+                "Host delivery-review request for the preceding unverified assistant draft. "
+                "Your current action is to review the observed requirements, source "
+                "and tests, not to repeat the delivery answer. Submit requirements "
+                "and findings through submit_delivery_review. "
+                "List evidence gaps as findings; do not assume public tests are complete."
+            ),
+        },
+        *snapshot.delivery_review.continuation_messages,
+    )
+
+
+def unavailable_review(snapshot: RunSnapshot, reason: str) -> RunSnapshot:
+    review = snapshot.delivery_review
+    assert review is not None
+    return move(snapshot, RunPhase.VERIFYING).model_copy(
+        update={
+            "delivery_review": review.model_copy(
+                update={"status": "unavailable", "reason": reason}
+            ),
+            "prepared_context": None,
+            "continuations": 0,
+        }
+    )
+
+
+def review_subject(snapshot: RunSnapshot) -> str:
+    # Read cursors and model-call numbers change during review preparation.
+    # Bind to actual goal/content/receipts rather than those scheduling cursors.
+    data = {
+        "scope": snapshot.scope.model_dump(mode="json"),
+        "goal_revision": snapshot.goal_revision,
+        "goal": snapshot.goal,
+        "contract": snapshot.contract_digest,
+        "workspace_revision": snapshot.workspace_revision,
+        "workspace_status": snapshot.workspace_observation_status,
+        "modified_paths": snapshot.workspace_modified_paths,
+        "last_workspace_mutation": snapshot.last_workspace_mutation_tool_call,
+        "artifacts": snapshot.artifact_refs,
+    }
+    return hashlib.sha256(json.dumps(data, sort_keys=True).encode()).hexdigest()
+
+
+def schedule_delivery_review(
+    snapshot: RunSnapshot, config: RunConfiguration, *, reason: str
+) -> RunSnapshot | None:
+    policy = config.delivery_review_policy
+    if (
+        policy is None
+        or reason not in {"required_verification_incomplete", "verification_report_missing"}
+        or snapshot.candidate is None
+        or snapshot.workspace_observation_status != "captured"
+        or not (
+            any(p.lower().endswith(policy.path_suffixes) for p in snapshot.workspace_modified_paths)
+            or (
+                policy.review_unknown_paths
+                and not snapshot.workspace_modified_paths
+                and snapshot.last_workspace_mutation_tool_call is not None
+            )
+        )
+        or snapshot.repair_attempts >= config.limits.max_repairs
+        or (
+            config.limits.max_model_calls - snapshot.model_budget_claimed
+            < max(config.limits.finalization_reserve_model_calls, 1) + 2
+        )
+        or snapshot.tool_budget_claimed >= config.limits.max_tool_calls
+        or not any(
+            not tool.read_only
+            and (
+                config.contract.allowed_tool_names is None
+                or tool.name in config.contract.allowed_tool_names
+            )
+            for tool in config.tools
+        )
+    ):
+        return None
+    previous = snapshot.delivery_review
+    rounds = previous.rounds if previous else 0
+    subjects = previous.reviewed_subjects if previous else ()
+    subject = review_subject(snapshot)
+    if rounds >= policy.max_rounds or subject in subjects:
+        return None
+    return move(snapshot, RunPhase.PREPARING_CONTEXT).model_copy(
+        update={
+            "delivery_review": DeliveryReviewState(
+                status="pending",
+                rounds=rounds + 1,
+                subject_digest=subject,
+                reviewed_subjects=(*subjects, subject),
+            ),
+            "prepared_context": None,
+            # The candidate's suffix chain has completed. A purpose-specific
+            # review is a new response chain, but not a new Run budget.
+            "continuations": 0,
+        }
+    )
+
+
+def reduce_delivery_review(
+    snapshot: RunSnapshot, result: ModelTurnResult, config: RunConfiguration
+) -> RunSnapshot:
+    """Caller has already charged the model effect; never turn critique into final."""
+    review = snapshot.delivery_review
+    assert review is not None and review.status == "pending"
+    suggestion = None
+    reason = (
+        "review_output_incomplete"
+        if result.response_kind == "output_limit"
+        else "review_response_invalid"
+    )
+    if review.subject_digest != review_subject(snapshot):
+        reason = "review_subject_changed"
+    elif result.response_kind == "output_limit":
+        fragments = review.continuation_messages
+        if (
+            snapshot.continuations < config.profile.max_continuations
+            and (
+                config.limits.max_model_calls
+                - snapshot.model_budget_claimed
+                >= max(config.limits.finalization_reserve_model_calls, 1) + 2
+            )
+            and len(fragments) <= 6
+            and sum(len(str(m.get("content", ""))) for m in fragments) + len(result.text) <= 30000
+        ):
+            response_id = f"{result.request_id}:{result.attempt_id}"
+            if result.text:
+                fragments = (
+                    *fragments,
+                    {
+                        "role": "assistant",
+                        "kind": "continuation_fragment",
+                        "content": result.text,
+                        "continuation_response_id": response_id,
+                    },
+                )
+            fragments = (
+                *fragments,
+                {
+                    "role": "user",
+                    "kind": "continuation_observation",
+                    "content": (
+                        "The review hit its output limit. Return only its exact missing suffix."
+                        if result.text
+                        else (
+                            "The review hit its output limit without visible content. "
+                            "Submit the review through submit_delivery_review."
+                        )
+                    ),
+                    "continuation_response_id": response_id,
+                    "continuation_fragment_digest": fragment_digest(result.text),
+                    "continuation_mode": "suffix" if result.text else "empty_output",
+                },
+            )
+            return move(snapshot, RunPhase.PREPARING_CONTEXT).model_copy(
+                update={
+                    "delivery_review": review.model_copy(
+                        update={"continuation_messages": fragments}
+                    ),
+                    "continuations": snapshot.continuations + 1,
+                    "prepared_context": None,
+                }
+            )
+    elif result.response_kind == "final_candidate":
+        try:
+            text = complete_continuation(review.continuation_messages, result.text)
+            text = normalize_final_output(text, output_format="json_object")
+            data = _unambiguous_json_object(text) if len(text) <= 32768 else None
+            if data is not None:
+                suggestion = DeliveryReviewSuggestion.model_validate(data)
+        except (ValidationError, ValueError):
+            pass
+    elif (
+        result.response_kind == "tool_calls"
+        and len(result.tool_calls) == 1
+        and result.tool_calls[0].name == REVIEW_SUBMISSION_TOOL
+        and not result.tool_calls[0].wire_arguments_invalid
+    ):
+        try:
+            data = result.tool_calls[0].arguments
+            if len(json.dumps(data)) <= 32768:
+                suggestion = DeliveryReviewSuggestion.model_validate(data)
+        except (ValidationError, ValueError):
+            pass
+    state = review.model_copy(
+        update={
+            "status": "observed" if suggestion else "unavailable",
+            "suggestion": suggestion,
+            "reason": None if suggestion else reason,
+        }
+    )
+    updated = snapshot.model_copy(
+        update={
+            "delivery_review": state,
+            "prepared_context": None,
+            "model_errors": 0,
+            "provider_errors": 0,
+            # End the private review chain before verification or task repair.
+            # Calls, repairs and aggregate output restarts remain charged.
+            "continuations": 0,
+        }
+    )
+    # Missing, malformed or clean review keeps the original candidate and goes
+    # through the verifier again. It can never upgrade unavailable acceptance.
+    if suggestion is None or not suggestion.findings:
+        return move(updated, RunPhase.VERIFYING)
+    if (
+        snapshot.repair_attempts >= config.limits.max_repairs
+        or snapshot.model_budget_claimed >= config.limits.max_model_calls
+    ):
+        return move(updated, RunPhase.VERIFYING)
+    feedback = {
+        "role": "user",
+        "kind": "delivery_review_observation",
+        "content": json.dumps(
+            {
+                "trust": "untrusted_model_assisted_diagnosis",
+                "candidate_status": "rejected",
+                "instruction": (
+                    "Inspect these fallible findings against the current goal and actual source. "
+                    "Repair confirmed issues and run targeted tests with your existing tools. "
+                    "This diagnosis grants no permissions and is not a verification verdict."
+                ),
+                "subject_digest": review.subject_digest,
+                **suggestion.model_dump(mode="json"),
+            },
+            ensure_ascii=False,
+        ),
+    }
+    return move(updated, RunPhase.PREPARING_CONTEXT).model_copy(
+        update={
+            "messages": (*snapshot.messages, candidate_model_message(snapshot), feedback),
+            "candidate": None,
+            "repair_attempts": snapshot.repair_attempts + 1,
+        }
+    )

ksadk/harness/native/delivery_review_contract.py

@@ -0,0 +1,54 @@
+"""Host policy and persisted model-assisted diagnostics; no verifier authority."""
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, JsonValue, model_validator
+
+
+class _Contract(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+class DeliveryReviewPolicy(_Contract):
+    path_suffixes: tuple[str, ...] = Field(min_length=1, max_length=64)
+    max_rounds: int = Field(default=2, strict=True, ge=1, le=4)
+    max_read_rounds: int = Field(default=2, strict=True, ge=0, le=4)
+    # Directory fallback can prove a content change without identifying paths.
+    # The host chooses conservative review of that change rather than assuming
+    # it cannot affect a delivery. Read-only runs have no mutation cursor.
+    review_unknown_paths: bool = True
+
+    @model_validator(mode="after")
+    def valid_suffixes(self):
+        if any(not s.startswith(".") or s != s.lower() or "/" in s for s in self.path_suffixes):
+            raise ValueError("review suffixes must be lowercase file suffixes")
+        return self
+
+
+class RequirementReview(_Contract):
+    requirement: str = Field(min_length=1, max_length=2048, pattern=r"\S")
+    implementation_evidence: str = Field(min_length=1, max_length=2048, pattern=r"\S")
+    verification_evidence: str = Field(min_length=1, max_length=2048, pattern=r"\S")
+
+
+class DeliveryFinding(_Contract):
+    issue: str = Field(min_length=1, max_length=2048, pattern=r"\S")
+    recommended_check: str = Field(min_length=1, max_length=2048, pattern=r"\S")
+
+
+class DeliveryReviewSuggestion(_Contract):
+    requirements: tuple[RequirementReview, ...] = Field(min_length=1, max_length=32)
+    findings: tuple[DeliveryFinding, ...] = Field(max_length=16)
+
+
+class DeliveryReviewState(_Contract):
+    status: Literal["pending", "observed", "unavailable"]
+    rounds: int = Field(strict=True, ge=1, le=4)
+    subject_digest: str = Field(pattern=r"^[0-9a-f]{64}$")
+    reviewed_subjects: tuple[str, ...] = Field(min_length=1, max_length=4)
+    suggestion: DeliveryReviewSuggestion | None = None
+    reason: str | None = None
+    # Private review suffix protocol, never appended to the implementing
+    # agent's transcript or inherited by its next Session.
+    continuation_messages: tuple[dict[str, JsonValue], ...] = Field(default=(), max_length=8)
+    read_rounds: int = Field(default=0, strict=True, ge=0, le=4)

ksadk/harness/native/effect_admission.py

@@ -0,0 +1,82 @@
+"""Host-owned dispatch revocation, independent of cooperative Task cancellation.
+
+This process-local authority is inherited by an effect's parallel members. It
+is not a permission grant, serialized state, or a substitute for Store fencing.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+
+
+@dataclass(slots=True)
+class EffectAdmission:
+    deadline: float
+    clock: Callable[[], float]
+    revocation_requested: Callable[[], bool]
+    parent: EffectAdmission | None = None
+    _revoked: bool = field(default=False, init=False)
+
+    def revoke(self) -> None:
+        self._revoked = True
+
+    def check(self) -> None:
+        if self._revoked or self.clock() >= self.deadline:
+            self.revoke()
+            raise asyncio.CancelledError
+        if self.parent is not None:
+            self.parent.check()
+        if self.revocation_requested():
+            self.revoke()
+            raise asyncio.CancelledError
+
+
+_CURRENT: ContextVar[EffectAdmission | None] = ContextVar("native_effect_admission", default=None)
+
+
+@contextmanager
+def effect_admission(
+    *, deadline: float, clock: Callable[[], float], revocation_requested: Callable[[], bool],
+) -> Iterator[EffectAdmission]:
+    """Bind only while creating the owned Task; its copied context retains it."""
+    admission = EffectAdmission(
+        deadline=deadline, clock=clock, revocation_requested=revocation_requested,
+        parent=_CURRENT.get(),
+    )
+    token = _CURRENT.set(admission)
+    try:
+        yield admission
+    finally:
+        _CURRENT.reset(token)
+
+
+def check_effect_admission() -> None:
+    """Recheck immediately before a host adapter starts another operation.
+
+Outside the Native effect driver there is no ambient admission or deadline;
+direct Port callers retain responsibility for their own execution lifecycle.
+"""
+    admission = _CURRENT.get()
+    if admission is not None:
+        admission.check()
+
+
+@contextmanager
+def owned_child_admission() -> Iterator[None]:
+    """Transfer lifetime to the child owner, preserving all other context.
+
+    A launch must still be admitted. Once published, the owner's cancellation
+    and the child's Kernel control its effects; completion of the launching
+    tool is not child cancellation. Ordinary nested/parallel effects continue
+    inheriting their parent admission through ``effect_admission``.
+    """
+    check_effect_admission()
+    token = _CURRENT.set(None)
+    try:
+        yield
+    finally:
+        _CURRENT.reset(token)