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

ksadk/harness/native/context.py

@@ -0,0 +1,358 @@
+"""Pure compaction validation; summaries never become execution authority.
+
+The host supplies token counts from its pinned model tokenizer and retains the
+original transcript. This module performs no model, storage, or artifact I/O.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_serializer, model_validator
+
+from .completion import VerificationRepairTarget
+
+NonBlank = Annotated[str, Field(min_length=1, pattern=r"\S")]
+TokenCount = Annotated[int, Field(strict=True, ge=0)]
+PositiveTokenCount = Annotated[int, Field(strict=True, ge=1)]
+
+
+class _ContextContract(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+
+class AcceptanceProgress(_ContextContract):
+    """A current-subject pass may still need a new final-candidate verdict."""
+
+    acceptance_id: NonBlank
+    required: bool
+    status: Literal["pending", "passed", "failed", "blocked"] = "pending"
+    last_verdict: Literal["passed", "failed", "not_run", "blocked"] | None = None
+    needs_reverification: bool = True
+    safe_summary: str = ""
+    evidence_refs: tuple[NonBlank, ...] = ()
+    verifier_id: NonBlank | None = None
+    verifier_version: NonBlank | None = None
+    verification_method: Literal["deterministic", "human", "model_assisted"] | None = None
+    repairable: bool | None = None
+    repair_target: VerificationRepairTarget | None = None
+
+
+class VerificationProgress(_ContextContract):
+    """Identity of the stored report; only a host-validated cursor grants trust."""
+
+    candidate_id: NonBlank
+    contract_revision: NonBlank
+    subject_digest: NonBlank
+    subject_context_digest: NonBlank | None = None
+    environment_digest: NonBlank
+    binding_validated: bool
+    tool_calls_at_verification: int | None = Field(default=None, strict=True, ge=0)
+    tool_calls_since_verification: int | None = Field(default=None, strict=True, ge=0)
+
+
+class PlanningProgress(_ContextContract):
+    # Preserve the stable TodoWrite identity across model turns and compaction.
+    # It remains model planning, without granting acceptance authority.
+    id: str | None = Field(default=None, min_length=1, max_length=180,
+                           exclude_if=lambda value: value is None)
+    content: NonBlank = Field(max_length=500)
+    status: Literal["pending", "in_progress", "completed"]
+    priority: Literal["high", "medium", "low"]
+    authority: Literal["model_planning_only"] = "model_planning_only"
+
+
+class SourceReadProgress(_ContextContract):
+    """Receipt-derived navigation, never permission, freshness or task coverage."""
+
+    path: NonBlank = Field(max_length=2048)
+    receipt_ref: NonBlank
+    tool_call_id: NonBlank
+    returned_lines: tuple[PositiveTokenCount, PositiveTokenCount]
+    # The configured clip is a navigation hint. The planner may retain a larger
+    # complete batch when it fits; these fields do not attest model observation.
+    configured_prefix_lines: tuple[PositiveTokenCount, PositiveTokenCount] | None
+    configured_next_start_line: PositiveTokenCount | None
+    total_lines: PositiveTokenCount
+    source_mtime_ns: TokenCount | None = None
+    source_size_bytes: TokenCount | None = None
+    source_payload_digest: str = Field(pattern=r"^sha256:[0-9a-f]{64}$")
+    source_freshness: Literal["not_attested"] = "not_attested"
+    semantic_coverage: Literal["not_attested"] = "not_attested"
+    authority: Literal["navigation_only"] = "navigation_only"
+
+    @model_validator(mode="after")
+    def coherent_navigation(self):
+        start, end = self.returned_lines
+        if not 1 <= start <= end <= self.total_lines:
+            raise ValueError("invalid returned source range")
+        if self.configured_prefix_lines is None:
+            if self.configured_next_start_line is not None:
+                raise ValueError("partial source line cannot provide a line cursor")
+        else:
+            first, last = self.configured_prefix_lines
+            if first != start or not first <= last <= end:
+                raise ValueError("source preview must be a continuous returned prefix")
+            expected = last + 1 if last < self.total_lines else None
+            if self.configured_next_start_line != expected:
+                raise ValueError("source cursor must follow the complete visible prefix")
+        return self
+
+
+class ExecutionContinuityState(_ContextContract):
+    """Host-owned facts; pending_work names repair gaps, not final rechecks."""
+
+    goal: NonBlank
+    goal_revision: int = Field(strict=True, ge=0)
+    contract_digest: NonBlank
+    required_acceptance_ids: tuple[NonBlank, ...]
+    pending_work: tuple[NonBlank, ...]
+    failure_fingerprints: tuple[NonBlank, ...]
+    evidence_refs: tuple[NonBlank, ...]
+    artifact_refs: tuple[NonBlank, ...]
+    next_action: NonBlank | None
+    workspace_revision: NonBlank | None
+    observed_progress_revision: int = Field(default=0, strict=True, ge=0)
+    workspace_state: Literal["initial", "captured", "unavailable"] = "unavailable"
+    workspace_changed_paths: tuple[NonBlank, ...] = ()
+    workspace_observation_reason: NonBlank | None = None
+    acceptance_progress: tuple[AcceptanceProgress, ...] = ()
+    last_verification: VerificationProgress | None = None
+    tool_receipt_refs: tuple[NonBlank, ...] = ()
+    task_progress: tuple[PlanningProgress, ...] = ()
+    task_progress_revision: int = Field(default=0, strict=True, ge=0)
+    # Verification debt is distinct from work the host has found defective.
+    # A candidate still goes through the completion verifier even when no
+    # repair is required; unchecked evidence is never a completion pass.
+    pending_verification: tuple[NonBlank, ...] = ()
+    # Generic tool content cannot attest to artifacts or a current code revision.
+    artifact_state: Literal["unknown", "available"] = "unknown"
+    pending_interaction_refs: tuple[NonBlank, ...] = ()
+    unresolved_observation_refs: tuple[NonBlank, ...] = ()
+    pending_subagent_refs: tuple[NonBlank, ...] = ()
+    pending_guidance_ids: tuple[NonBlank, ...] = Field(
+        default=(), exclude_if=lambda value: not value
+    )
+    # Parent-accounted locators, distinct from pending execution or acceptance.
+    accounted_subagent_run_ids: tuple[NonBlank, ...] = ()
+    source_read_progress: tuple[SourceReadProgress, ...] = ()
+    # Host-owned delivery debt, separate from plugin content and task goals.
+    pending_hook_operation_keys: tuple[NonBlank, ...] = ()
+    context_source_operation_key: str | None = Field(default=None, min_length=1,
+                                                    exclude_if=lambda value: value is None)
+
+    @model_serializer(mode="wrap")
+    def omit_unconfigured_subagents(self, serialize):
+        payload = serialize(self)
+        if not self.accounted_subagent_run_ids:
+            payload.pop("accounted_subagent_run_ids", None)
+        if not self.source_read_progress:
+            payload.pop("source_read_progress", None)
+        if not self.pending_hook_operation_keys:
+            payload.pop("pending_hook_operation_keys", None)
+        return payload
+
+    pending_tool_call_ids: tuple[NonBlank, ...] = ()
+
+    @model_validator(mode="after")
+    def unique_required_and_pending_ids(self) -> ExecutionContinuityState:
+        for identities in (
+            self.required_acceptance_ids,
+            self.pending_hook_operation_keys,
+            self.pending_tool_call_ids,
+            tuple(item.acceptance_id for item in self.acceptance_progress),
+            self.tool_receipt_refs,
+            self.accounted_subagent_run_ids,
+            tuple(item.path for item in self.source_read_progress),
+            self.pending_verification,
+        ):
+            if len(set(identities)) != len(identities):
+                raise ValueError("duplicate acceptance or pending tool identity")
+        if not set(self.pending_verification).issubset(self.required_acceptance_ids):
+            raise ValueError("pending verification must name required acceptances")
+        return self
+
+
+class ContextMessage(_ContextContract):
+    """Transcript reference, full raw payload digest, and trusted model-view cost.
+
+    Request assembly must resolve ``message_id`` against the original transcript;
+    this metadata cannot substitute for tool arguments or multimodal payloads.
+    """
+
+    message_id: NonBlank
+    payload_digest: NonBlank
+    role: Literal["system", "user", "assistant", "tool"]
+    content: str
+    token_count: PositiveTokenCount
+    tool_call_ids: tuple[NonBlank, ...] = ()
+    tool_result_for: NonBlank | None = None
+
+    @model_validator(mode="after")
+    def valid_tool_metadata(self) -> ContextMessage:
+        if self.tool_call_ids and self.role != "assistant":
+            raise ValueError("only assistant messages may declare tool calls")
+        if (self.role == "tool") != (self.tool_result_for is not None):
+            raise ValueError("tool results require the tool role and a call identity")
+        if len(set(self.tool_call_ids)) != len(self.tool_call_ids):
+            raise ValueError("duplicate tool call identity")
+        return self
+
+
+class ContextBudget(_ContextContract):
+    window_tokens: PositiveTokenCount
+    max_output_tokens: PositiveTokenCount
+    fixed_tokens: TokenCount = 0
+
+    @model_validator(mode="after")
+    def reserve_fits_window(self) -> ContextBudget:
+        if self.max_output_tokens + self.fixed_tokens > self.window_tokens:
+            raise ValueError("output and fixed reserves exceed the context window")
+        return self
+
+    @property
+    def input_capacity(self) -> int:
+        return self.window_tokens - self.max_output_tokens - self.fixed_tokens
+
+
+class CompactionEnvelope(_ContextContract):
+    source_revision: int = Field(strict=True, ge=0)
+    continuity: ExecutionContinuityState
+    continuity_digest: NonBlank
+    summary_text: NonBlank
+    summary_token_count: PositiveTokenCount
+    preserved_message_refs: tuple[NonBlank, ...]
+    validator_version: Literal["ksadk.compaction/v1"] = "ksadk.compaction/v1"
+
+
+class CompactionProjection(_ContextContract):
+    """Low-trust request context, never an assistant final or a Run outcome."""
+
+    kind: Literal["compaction_summary"] = "compaction_summary"
+    trust: Literal["untrusted"] = "untrusted"
+    purpose: Literal["context_only"] = "context_only"
+    source_revision: int
+    continuity_digest: NonBlank
+    summary_text: NonBlank
+    messages: tuple[ContextMessage, ...]
+    total_reserved_tokens: PositiveTokenCount
+
+
+class CompactionRejected(ValueError):
+    """Host must retain the previous context and repair or block compaction."""
+
+
+def continuity_digest(state: ExecutionContinuityState) -> str:
+    encoded = json.dumps(
+        state.model_dump(mode="json"), sort_keys=True, separators=(",", ":"), ensure_ascii=False
+    ).encode("utf-8")
+    return hashlib.sha256(encoded).hexdigest()
+
+
+def _tool_groups(
+    messages: tuple[ContextMessage, ...],
+) -> tuple[tuple[frozenset[str], ...], frozenset[str], frozenset[str]]:
+    """Return complete groups, unfinished group refs, and unresolved call IDs."""
+    message_ids: set[str] = set()
+    call_ids: set[str] = set()
+    pending: set[str] = set()
+    current_group: set[str] = set()
+    complete_groups: list[frozenset[str]] = []
+    for message in messages:
+        if message.message_id in message_ids:
+            raise CompactionRejected("duplicate_message_identity")
+        message_ids.add(message.message_id)
+        if message.role == "tool":
+            if message.tool_result_for not in pending:
+                raise CompactionRejected("orphan_or_duplicate_tool_result")
+            pending.remove(message.tool_result_for)
+            current_group.add(message.message_id)
+            if not pending:
+                complete_groups.append(frozenset(current_group))
+                current_group = set()
+        elif pending:
+            raise CompactionRejected("interleaved_pending_tool_protocol")
+        elif message.tool_call_ids:
+            if call_ids.intersection(message.tool_call_ids):
+                raise CompactionRejected("duplicate_tool_call_identity")
+            call_ids.update(message.tool_call_ids)
+            pending.update(message.tool_call_ids)
+            current_group.add(message.message_id)
+    return tuple(complete_groups), frozenset(current_group), frozenset(pending)
+
+
+def _preserve_messages(
+    old: tuple[ContextMessage, ...],
+    new: tuple[ContextMessage, ...],
+    continuity: ExecutionContinuityState,
+) -> None:
+    groups, pending_refs, pending_ids = _tool_groups(old)
+    if pending_ids != frozenset(continuity.pending_tool_call_ids):
+        raise CompactionRejected("pending_tool_state_mismatch")
+    old_index = {message.message_id: index for index, message in enumerate(old)}
+    retained = frozenset(message.message_id for message in new)
+    if not pending_refs.issubset(retained):
+        raise CompactionRejected("pending_tool_protocol_lost")
+    for group in groups:
+        if group.intersection(retained) and not group.issubset(retained):
+            raise CompactionRejected("partial_tool_group")
+    previous_index = -1
+    for message in new:
+        index = old_index.get(message.message_id)
+        if index is None:
+            raise CompactionRejected("unknown_message")
+        if index <= previous_index:
+            raise CompactionRejected("message_order_or_identity_changed")
+        if message != old[index]:
+            raise CompactionRejected("retained_message_changed")
+        previous_index = index
+    _, new_pending_refs, new_pending_ids = _tool_groups(new)
+    if new_pending_refs != pending_refs or new_pending_ids != pending_ids:
+        raise CompactionRejected("pending_tool_protocol_changed")
+
+
+def validate_compaction(
+    *,
+    source_revision: int,
+    continuity: ExecutionContinuityState,
+    old_messages: tuple[ContextMessage, ...],
+    new_messages: tuple[ContextMessage, ...],
+    envelope: CompactionEnvelope,
+    budget: ContextBudget,
+) -> CompactionProjection:
+    """Validate a proposal before a CAS commit against ``source_revision``.
+
+    Rejection must not overwrite the committed continuity state or transcript.
+    ``fixed_tokens`` includes system/tool schemas, structured continuity, and
+    message framing; message/summary counts must use the same model tokenizer.
+    Artifact resolution, scope checks, and summary consistency belong to ports.
+    """
+    if type(source_revision) is not int or source_revision < 0:
+        raise CompactionRejected("invalid_source_revision")
+    if envelope.source_revision != source_revision:
+        raise CompactionRejected("source_revision_mismatch")
+    if envelope.continuity != continuity:
+        raise CompactionRejected("continuity_mismatch")
+    digest = continuity_digest(continuity)
+    if envelope.continuity_digest != digest:
+        raise CompactionRejected("continuity_digest_mismatch")
+    if envelope.preserved_message_refs != tuple(item.message_id for item in new_messages):
+        raise CompactionRejected("message_manifest_mismatch")
+    _preserve_messages(old_messages, new_messages, continuity)
+    total = (
+        sum(message.token_count for message in new_messages)
+        + envelope.summary_token_count
+        + budget.fixed_tokens
+        + budget.max_output_tokens
+    )
+    if total > budget.window_tokens:
+        raise CompactionRejected("context_window_exceeded")
+    return CompactionProjection(
+        source_revision=source_revision,
+        continuity_digest=digest,
+        summary_text=envelope.summary_text,
+        messages=new_messages,
+        total_reserved_tokens=total,
+    )

ksadk/harness/native/context_artifact_page.py

@@ -0,0 +1,75 @@
+"""Pure recognition of a host-declared artifact reader's returned text page.
+
+Callers must first check the locked ToolDefinition. Source JSON, tool names
+and similarly shaped prose never grant this role or storage access.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+
+from .context_history import _unambiguous_json_object
+from .ports import ArtifactReadResult, ArtifactRef
+
+
+def artifact_page_observation(message, *, arguments):
+    if message.get("role") != "tool" or not isinstance(arguments, dict):
+        return None
+    receipt = _unambiguous_json_object(message.get("content"))
+    payload = receipt.get("content") if receipt and receipt.get("status") == "ok" else None
+    if not isinstance(payload, dict):
+        return None
+    uri = arguments.get("uri")
+    offset, limit = arguments.get("offset_chars", 0), arguments.get("limit_chars", 16000)
+    text = payload.get("content")
+    if (
+        not isinstance(uri, str) or payload.get("uri") != uri
+        or type(offset) is not int or offset < 0
+        or type(limit) is not int or not 1 <= limit <= 32000
+        or payload.get("offset_chars") != offset
+        or type(payload.get("complete")) is not bool
+        or not isinstance(text, str) or len(text) > limit
+    ):
+        return None
+    try:
+        ref = ArtifactRef.model_validate({
+            key: payload[key] for key in ("uri", "content_hash", "size_bytes", "mime_type")
+        })
+        ArtifactReadResult.model_validate({
+            "ref": ref, "content": text, "offset_chars": payload["offset_chars"],
+            "next_offset_chars": payload["next_offset_chars"], "complete": payload["complete"],
+        })
+        if offset == 0 and payload["complete"] and (
+            ref.size_bytes != len(text.encode("utf-8"))
+            or ref.content_hash != "sha256:" + hashlib.sha256(text.encode("utf-8")).hexdigest()
+        ):
+            return None
+    except (ValueError, TypeError, KeyError):
+        return None
+    # Retain exact text and metadata, including incomplete-page state. This
+    # is a quoted observation, not a grant to open the URI or a fresh file read.
+    return json.loads(json.dumps(message, ensure_ascii=False))
+
+
+def complete_artifact_call_ids(messages, *, tool_names):
+    calls = {}
+    observed = set()
+    for message in messages:
+        if message.get("role") == "assistant":
+            for call in message.get("tool_calls", ()):
+                function = call.get("function", {})
+                if function.get("name") in tool_names:
+                    arguments = _unambiguous_json_object(function.get("arguments"))
+                    if arguments is not None:
+                        calls[call["id"]] = arguments
+        elif message.get("role") == "tool":
+            call_id = message.get("tool_call_id")
+            if call_id in calls and artifact_page_observation(
+                message, arguments=calls[call_id]
+            ) is not None:
+                observed.add(call_id)
+    return frozenset(observed)
+
+
+__all__ = ["artifact_page_observation", "complete_artifact_call_ids"]

ksadk/harness/native/context_compaction_projection.py

@@ -0,0 +1,131 @@
+"""Pure validation and history construction for a covered compaction projection."""
+
+from __future__ import annotations
+
+from .context import (
+    CompactionEnvelope,
+    CompactionRejected,
+    ExecutionContinuityState,
+    continuity_digest,
+    validate_compaction,
+)
+from .context_history import ContextRuntimeError
+from .context_replay import compaction_replay_view
+from .context_runtime_contracts import (
+    CompactionHistory,
+    CompactionProjectionOverflow,
+    CompactionRequest,
+    CompactionResult,
+    Messages,
+    _compacted_messages,
+    _refs,
+    _resume,
+    _summary,
+)
+
+
+def seal_compaction_projection(
+    planner,
+    request: CompactionRequest,
+    summary_text: str,
+    current_continuity: ExecutionContinuityState,
+    current_messages: Messages,
+) -> CompactionResult:
+    """Validate an authorized retained projection; callers prove coverage first."""
+    raw_by_ref = dict(zip(_refs(current_messages), current_messages))
+    retained = tuple(raw_by_ref[ref] for ref in request.retained_message_refs)
+    if retained != request.retained_messages:
+        raise ContextRuntimeError("context_source_changed")
+    read_view = planner._read_view(
+        retained,
+        frozenset(request.source_reader_names),
+        frozenset(request.protected_reader_call_ids),
+    )
+    read_view = compaction_replay_view(
+        read_view, request.retained_message_refs,
+        covered_refs=request.history.retained_message_refs, profile=request.profile,
+        root_prefix_digest=request.history.prefix_digest,
+    )
+    new_metadata = planner._metadata(
+        request.retained_message_refs,
+        retained,
+        counted_messages=read_view,
+        profile=request.profile,
+    )
+    envelope = CompactionEnvelope(
+        source_revision=request.source_revision,
+        continuity=current_continuity,
+        continuity_digest=continuity_digest(current_continuity),
+        summary_text=summary_text,
+        summary_token_count=(
+            planner._count_message(_summary(summary_text))
+            + planner._count_message(_resume())
+        ),
+        preserved_message_refs=request.retained_message_refs,
+    )
+    try:
+        projection = validate_compaction(
+            source_revision=request.source_revision,
+            continuity=current_continuity,
+            old_messages=request.old_messages,
+            new_messages=new_metadata,
+            envelope=envelope,
+            budget=request.budget,
+        )
+    except CompactionRejected as exc:
+        if str(exc) == "context_window_exceeded":
+            raise CompactionProjectionOverflow("context_compaction_validation_failed") from exc
+        raise ContextRuntimeError("context_compaction_validation_failed") from exc
+    # Validate unchanged source identities/costs under the previous root
+    # first. The committed rewrite then starts a new dispatch-only view.
+    read_view = compaction_replay_view(
+        read_view, request.retained_message_refs,
+        covered_refs=request.retained_message_refs, profile=request.profile,
+        root_prefix_digest=request.source_context_digest,
+    )
+    prepared = planner._prepared(
+        request.instructions,
+        _compacted_messages(summary_text, read_view, current_continuity.goal),
+        request.budget.fixed_tokens,
+        request.turn_control,
+        profile=request.profile,
+        goal=current_continuity.goal,
+        abandoned=request.history.abandoned_replay_digests,
+        replay_header_digest=request.replay_header_digest,
+    )
+    if prepared.counted_input_tokens + request.profile.max_output_tokens > (
+        request.profile.context_window
+    ):
+        raise CompactionProjectionOverflow("context_compaction_validation_failed")
+    history = CompactionHistory(
+        abandoned_replay_digests=prepared.abandoned_replay_digests,
+        prior_compactions=request.history.prior_compactions,
+        count=request.history.count + 1,
+        stagnant_count=(
+            1
+            if request.history.count == 0
+            or (
+                current_continuity.observed_progress_revision
+                > request.history.last_observed_progress_revision
+            )
+            or (
+                current_continuity.workspace_revision is not None
+                and current_continuity.workspace_revision
+                != request.history.last_workspace_revision
+            )
+            else request.history.stagnant_count + 1
+        ),
+        last_workspace_revision=current_continuity.workspace_revision,
+        last_observed_progress_revision=current_continuity.observed_progress_revision,
+        last_model_turn=request.model_turn,
+        prefix_message_count=request.source_message_count,
+        prefix_digest=request.source_context_digest,
+        contract_digest=current_continuity.contract_digest,
+        retained_message_refs=request.retained_message_refs,
+        summary_text=summary_text,
+        tokenizer_id=planner.tokenizer_id,
+        provider_replay_projection_policy=request.profile.provider_replay_projection_policy,
+        summary_completion_policy=request.summary_completion_policy,
+        summary_output_limited=request.summary_output_limited,
+    )
+    return CompactionResult(projection=projection, prepared=prepared, history=history)