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

ksadk/harness/native/context_pruning.py

@@ -0,0 +1,275 @@
+"""Bound historical tool-output projections without changing the transcript."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+
+from pydantic import JsonValue
+
+from .context_history import _historical_message
+
+Messages = tuple[dict[str, JsonValue], ...]
+
+
+def _json(value: object) -> str:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def _excerpt_payload(text: str, limit: int, *, kind: str) -> dict[str, JsonValue]:
+    head = limit // 2
+    tail = limit - head
+    return {
+        "type": kind,
+        "original_chars": len(text),
+        "omitted_chars": len(text) - limit,
+        "payload_digest": hashlib.sha256(text.encode("utf-8")).hexdigest(),
+        "head": text[:head],
+        "tail": text[-tail:],
+    }
+
+
+def _excerpt(text: str, limit: int, *, kind: str = "historical_tool_result_excerpt") -> str:
+    if len(text) <= limit:
+        return text
+    return _json(_excerpt_payload(text, limit, kind=kind))
+
+
+def _fresh_line_preview(source: dict, max_chars: int) -> dict | None:
+    """Keep a continuous prefix of a recognized line-reader response.
+
+    A historical head/tail excerpt is not a fresh source page: its middle is
+    missing and its tail may start inside a line. Derive the visible range from
+    complete returned lines, keeping the executed source range separately.
+    Never advance past a line whose content did not fit in the model view.
+    """
+    start, end, total = (source.get(key) for key in ("start_line", "end_line", "total_lines"))
+    read_range = source.get("read_range")
+    count = source.get("line_count")
+    if (
+        any(type(value) is not int for value in (start, end, total, count))
+        or not 1 <= start <= end <= total
+        or count != end - start + 1
+        or not isinstance(read_range, dict)
+        or any(type(read_range.get(key)) is not int for key in ("start", "end"))
+        or read_range != {"start": start, "end": end}
+    ):
+        return None
+    text = source["content"]
+    prefix = text[:max_chars]
+    boundary = prefix.rfind("\n")
+    complete_lines = prefix[:boundary].count("\n") + 1 if boundary >= 0 else 0
+    if complete_lines >= count:
+        return None
+    visible = prefix[:boundary] if complete_lines else prefix
+    visible_end = start + complete_lines - 1 if complete_lines else None
+    copied = {
+        **source,
+        "content": visible,
+        "source_read_range": source.get("source_read_range", dict(read_range)),
+        "end_line": visible_end,
+        "read_range": {"start": start, "end": visible_end} if complete_lines else None,
+        "line_count": complete_lines,
+        "next_start_line": visible_end + 1 if complete_lines else None,
+        "preview_chars": len(visible),
+        "partial": True,
+        "truncated": True,
+        "context_projection": {
+            "type": "workspace_read_prefix",
+            "original_chars": len(text),
+            "omitted_chars": len(text) - len(visible),
+            "payload_digest": hashlib.sha256(text.encode("utf-8")).hexdigest(),
+        },
+    }
+    if complete_lines:
+        copied["suggested_action"] = (
+            f"This context view contains complete lines {start}-{visible_end}; "
+            f"continue reading at line {visible_end + 1} for omitted source."
+        )
+    else:
+        copied["partial_line"] = start
+        copied["suggested_action"] = (
+            f"Only part of line {start} fits in this context view. No line continuation "
+            "can recover its missing text; use a bound search or other permitted "
+            "inspection tool for the remaining part of this line."
+        )
+    return copied
+
+
+def project_workspace_read_result(
+    message: dict[str, JsonValue], *, path: str, max_chars: int
+) -> dict[str, JsonValue] | None:
+    """Project a host-identified read for either main or summary context.
+
+    The caller authorizes the reader and obtains its path from the actual call.
+    A source page stays structured historical data with an honest visible range;
+    clipping the serialized receipt instead would hide source facts behind
+    envelope text while leaving a misleading full range in its prefix.
+    """
+    if type(max_chars) is not int or max_chars < 128:
+        raise ValueError("workspace read limit must be at least 128 characters")
+    if message.get("role") != "tool" or not isinstance(message.get("content"), str):
+        return None
+    try:
+        receipt = json.loads(message["content"])
+        source = receipt.get("content")
+        if (
+            not path
+            or receipt.get("status") != "ok"
+            or not isinstance(source, dict)
+            or source.get("ok") is not True
+            or source.get("path") != path
+            or not isinstance(source.get("content"), str)
+        ):
+            return None
+        if len(source["content"]) > max_chars:
+            preview = _fresh_line_preview(source, max_chars)
+            if preview is not None:
+                receipt["content"] = preview
+            else:
+                source["content"] = json.loads(
+                    _excerpt(source["content"], max_chars, kind="workspace_read_excerpt")
+                )
+                source["truncated"] = True
+        return {**message, "content": _json(receipt)}
+    except (ValueError, TypeError, AttributeError):
+        return None
+
+
+def project_fresh_workspace_reads(
+    messages: Messages,
+    *,
+    reader_names: frozenset[str],
+    max_chars: int,
+    protected_call_ids: frozenset[str] = frozenset(),
+) -> Messages | None:
+    """Bound source reads throughout the active view, keeping complete batches.
+
+    Only host-declared source readers are eligible: the original source remains
+    accessible through the same bound reader. Other results in a mixed batch,
+    failures and media stay intact. Rebuild every view from the full receipts,
+    so the next model turn cannot resurrect an earlier oversized observation.
+    """
+    projected, clipped, index = list(messages), False, 0
+    try:
+        while index < len(messages):
+            assistant = messages[index]
+            calls = assistant.get("tool_calls")
+            if assistant.get("role") == "tool":
+                return None
+            if assistant.get("role") != "assistant" or not calls:
+                index += 1
+                continue
+            by_id = {call["id"]: call for call in calls}
+            end = index + 1
+            while end < len(messages) and messages[end].get("role") == "tool":
+                end += 1
+            results = messages[index + 1 : end]
+            if len(by_id) != len(calls) or len(results) != len(calls):
+                return None
+            seen = set()
+            for position, message in enumerate(results, index + 1):
+                call_id = message.get("tool_call_id")
+                if call_id not in by_id or call_id in seen:
+                    return None
+                seen.add(call_id)
+                call = by_id[call_id]
+                if call_id in protected_call_ids:
+                    continue
+                if call["function"]["name"] not in reader_names:
+                    continue
+                if not isinstance(message.get("content"), str):
+                    continue
+                path = json.loads(call["function"]["arguments"]).get("path")
+                if not isinstance(path, str):
+                    continue
+                view = project_workspace_read_result(message, path=path, max_chars=max_chars)
+                if view is not None and view["content"] != _json(json.loads(message["content"])):
+                    clipped = True
+                    projected[position] = view
+            index = end
+        return tuple(projected) if clipped else None
+    except (ValueError, KeyError, TypeError, AttributeError):
+        return None
+
+
+def project_tool_result(message: dict[str, JsonValue], *, max_chars: int) -> dict[str, JsonValue]:
+    """Return a detached historical projection with bounded textual output."""
+    if type(max_chars) is not int or max_chars < 128:
+        raise ValueError("historical tool result limit must be at least 128 characters")
+    copied = json.loads(_json(message))
+    if copied.get("role") != "tool":
+        return copied
+    content = copied.get("content")
+    if isinstance(content, str):
+        copied["content"] = _excerpt(content, max_chars)
+        return copied
+    if not isinstance(content, list):
+        return copied
+    text = "\n".join(
+        block.get("text", "")
+        for block in content
+        if isinstance(block, dict) and block.get("type") == "text"
+    )
+    media = [block for block in content if isinstance(block, dict) and block.get("type") != "text"]
+    copied["content"] = (
+        [{"type": "text", "text": _excerpt(text, max_chars)}] if text else []
+    ) + media
+    return copied
+
+
+def project_historical_tool_result(
+    message: dict[str, JsonValue], *, max_chars: int
+) -> tuple[dict, tuple[dict, ...]]:
+    """Quote host-generated excerpts as data without another JSON string layer.
+
+    Derive the excerpt from the authoritative source and the same host limit.
+    Tool text never proves its own projection type. Live model projection and
+    canonical receipts keep their existing string/media contracts.
+    """
+    projected = project_tool_result(message, max_chars=max_chars)
+    quoted, images = _historical_message(projected)
+    if message.get("role") != "tool":
+        return quoted, images
+    source = message.get("content")
+    if isinstance(source, str):
+        text = source
+    elif isinstance(source, list):
+        text = "\n".join(
+            block.get("text", "")
+            for block in source
+            if isinstance(block, dict) and block.get("type") == "text"
+        )
+    else:
+        return quoted, images
+    if len(text) <= max_chars:
+        return quoted, images
+    excerpt = _excerpt_payload(text, max_chars, kind="historical_tool_result_excerpt")
+    # Historical message fields are quoted JSON, not executable model blocks.
+    # For media, only the generated first text excerpt changes representation;
+    # the explicit image references and pixels are kept by _historical_message.
+    quoted["content"] = excerpt if isinstance(source, str) else [excerpt, *quoted["content"][1:]]
+    return quoted, images
+
+
+def clear_tool_result(
+    projected: dict[str, JsonValue], *, source_message_ref: str, payload_digest: str
+) -> dict[str, JsonValue]:
+    """Clear an older quoted result while retaining identity and explicit media."""
+    copied = json.loads(_json(projected))
+    marker = _json(
+        {
+            "type": "historical_tool_result_cleared",
+            "source_message_ref": source_message_ref,
+            "payload_digest": payload_digest,
+        }
+    )
+    content = copied.get("content")
+    if isinstance(content, list):
+        media = [
+            block for block in content if isinstance(block, dict) and block.get("type") != "text"
+        ]
+        copied["content"] = [{"type": "text", "text": marker}, *media]
+    else:
+        copied["content"] = marker
+    return copied

ksadk/harness/native/context_reduction.py

@@ -0,0 +1,60 @@
+"""Repartition original history after a sealed summary exceeds its task window."""
+
+from .context import ExecutionContinuityState
+from .context_runtime import CompactionHistory, CompactionRequest, ContextPlanner
+from .delivery_review import delivery_review_messages
+from .ports import RunConfiguration
+from .state import RunSnapshot
+from .tool_budget import model_instructions, model_tool_catalog, model_turn_control
+
+SUMMARY_REDUCTION_POLICY = "original-history-summary-reduction/v1"
+
+
+def replan_summary_projection(
+    planner: ContextPlanner,
+    snapshot: RunSnapshot,
+    updated: RunSnapshot,
+    config: RunConfiguration,
+    continuity: ExecutionContinuityState,
+) -> RunSnapshot | None:
+    # A second failure of the reduced selection must block. Model calls still
+    # consume the original Run budget; this is not an extra retry allowance.
+    if snapshot.force_compaction or snapshot.compaction_request is None:
+        return None
+    previous = CompactionRequest.model_validate(snapshot.compaction_request)
+    plan = planner.plan(
+        source_revision=snapshot.revision,
+        model_turn=updated.model_calls,
+        profile=config.profile,
+        instructions=model_instructions(snapshot, config),
+        tools=model_tool_catalog(snapshot, config),
+        context_tools=config.tools,
+        messages=delivery_review_messages(snapshot),
+        continuity=continuity,
+        contract=config.contract,
+        history=CompactionHistory.model_validate(snapshot.compaction_history),
+        force_compaction=True,
+        turn_control=model_turn_control(snapshot, config),
+    )
+    if plan.action != "compact":
+        return None
+    request = plan.request
+    # Every newly demoted complete group is quoted from the original history
+    # by the normal coverage planner. Do not drop it from an already sealed
+    # summary, alter source bytes, or repeat an identical selection.
+    if (
+        request.source_context_digest != previous.source_context_digest
+        or request.continuity != previous.continuity
+        or request.profile != previous.profile
+        or not set(request.retained_message_refs) < set(previous.retained_message_refs)
+    ):
+        return None
+    return updated.model_copy(
+        update={
+            "force_compaction": True,
+            "compaction_request": request.model_dump(mode="json"),
+            "prepared_context": None,
+            "model_errors": 0,
+            "provider_errors": 0,
+        }
+    )

ksadk/harness/native/context_replay.py

@@ -0,0 +1,148 @@
+"""Explicit private replay views rooted in the original sealed compaction."""
+
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+from typing import Literal
+
+from pydantic import Field
+
+from ksadk._model_anthropic import anthropic_content
+from ksadk._model_json import load_model_json
+
+from .model import ModelProfile, ModelReplayMetadata
+from .state import Contract
+
+POLICY = "anthropic-client-compaction/v1"
+
+
+class CompactionReplayView(Contract):
+    version: Literal["anthropic-client-compaction/v1"] = POLICY
+    profile_digest: str = Field(pattern=r"^[0-9a-f]{64}$", strict=True)
+    root_prefix_digest: str = Field(pattern=r"^[0-9a-f]{64}$", strict=True)
+    origin_message_ref: str = Field(min_length=1, strict=True)
+    original_content_digest: str = Field(pattern=r"^[0-9a-f]{64}$", strict=True)
+
+
+def _content_digest(blocks):
+    return hashlib.sha256(json.dumps(blocks, ensure_ascii=False, sort_keys=True,
+                                     separators=(",", ":")).encode()).hexdigest()
+
+
+def _mark(message, ref, root):
+    copied = copy.deepcopy(message)
+    if message.get("role") != "assistant" or message.get("provider_replay") is None:
+        return copied
+    replay = ModelReplayMetadata.model_validate(message["provider_replay"])
+    if replay.anthropic_content_json is None:
+        return copied
+    blocks = anthropic_content(load_model_json(replay.anthropic_content_json))
+    if not any(b["type"] in {"thinking", "redacted_thinking"} for b in blocks):
+        return copied
+    copied["provider_replay_projection"] = CompactionReplayView(
+        profile_digest=replay.profile_digest, root_prefix_digest=root,
+        origin_message_ref=ref, original_content_digest=_content_digest(blocks),
+    ).model_dump(mode="json")
+    return copied
+
+
+def compaction_replay_view(messages, refs, *, covered_refs, profile, root_prefix_digest):
+    if len(messages) != len(refs):
+        raise ValueError("compaction_replay_manifest_mismatch")
+    if profile.provider_replay_projection_policy != POLICY:
+        return copy.deepcopy(messages)
+    covered = frozenset(covered_refs)
+    return tuple(_mark(m, ref, root_prefix_digest) if ref in covered else copy.deepcopy(m)
+                 for ref, m in zip(refs, messages))
+
+
+def imported_compaction_replay(messages, *, policy, root_prefix_digest):
+    if policy != POLICY:
+        return copy.deepcopy(messages)
+    # Re-expanding the raw transcript also changes the prefix of post-compaction
+    # replies. All inherited thinking belongs to that old request root.
+    return tuple(_mark(m, f"imported-message:{i}", root_prefix_digest)
+                 for i, m in enumerate(messages))
+
+
+def reset_steered_replay(before, updated, configuration):
+    """Record a source-bound view only when a host contract rewrites the prefix."""
+    if configuration is None or configuration.profile.provider_replay_projection_policy != POLICY:
+        return updated, None
+    from .completion import TaskContract
+    from .context_runtime_contracts import _refs, source_context_digest
+    from .tool_budget import model_tool_catalog
+
+    previous = configuration.with_task_contract(TaskContract.model_validate(before.task_contract))
+    current = configuration.with_task_contract(TaskContract.model_validate(updated.task_contract))
+    reexpanded = bool(before.compaction_history.get("count", 0))
+    catalog_changed = model_tool_catalog(before, previous) != model_tool_catalog(updated, current)
+    if not reexpanded and not catalog_changed:
+        return updated, None
+    root = source_context_digest(before.messages)
+    refs = _refs(updated.messages)
+    messages = compaction_replay_view(
+        updated.messages, refs, covered_refs=refs[:len(before.messages)],
+        profile=configuration.profile, root_prefix_digest=root,
+    )
+    if configuration.profile.operator_guidance_policy == "journaled-system/v1":
+        from .operator_guidance import GUIDANCE_KIND, latest_guidance
+
+        for index, original in enumerate(before.messages):
+            if original.get("kind") != GUIDANCE_KIND:
+                continue
+            frame = latest_guidance((original,), configuration.profile)
+            if frame is None:
+                continue
+            messages[index]["operator_history_projection"] = CompactionReplayView(
+                profile_digest=configuration.profile.digest, root_prefix_digest=root,
+                origin_message_ref=refs[index],
+                original_content_digest=_content_digest(frame["content"]),
+            ).model_dump(mode="json")
+    return updated.model_copy(update={"messages": messages}), {
+        "policy": POLICY,
+        "reason": "contract_context_reexpanded" if reexpanded else "contract_tool_catalog_changed",
+        "root_prefix_digest": root,
+        "source_message_count": len(before.messages),
+        "goal_revision": updated.goal_revision,
+    }
+
+
+def steered_operator_view(source, profile):
+    """Quote obsolete host frames after an admitted contract prefix rewrite."""
+    raw = source.get("operator_history_projection")
+    if raw is None:
+        return None
+    from .operator_guidance import (
+        GUIDANCE_KIND,
+        HISTORICAL_FRAME_KIND,
+        latest_guidance,
+        quoted_operator_message,
+    )
+
+    view = CompactionReplayView.model_validate(raw)
+    original = source
+    if (source.get("kind") == HISTORICAL_FRAME_KIND
+            and source.get("history_original_kind") == GUIDANCE_KIND):
+        original = {**source, "kind": GUIDANCE_KIND}
+    frame = latest_guidance((original,), profile)
+    if (frame is None or profile.provider_replay_projection_policy != POLICY
+            or view.profile_digest != profile.digest
+            or view.original_content_digest != _content_digest(source.get("content"))):
+        raise ValueError("steered_operator_view_mismatch")
+    return quoted_operator_message(source)
+
+
+def replay_content_view(source, profile: ModelProfile, replay: ModelReplayMetadata):
+    blocks = anthropic_content(load_model_json(replay.anthropic_content_json))
+    raw = source.get("provider_replay_projection")
+    if raw is None:
+        return blocks
+    view = CompactionReplayView.model_validate(raw)
+    if (source.get("role") != "assistant" or profile.provider_replay_projection_policy != POLICY
+            or view.profile_digest != profile.digest
+            or view.original_content_digest != _content_digest(blocks)):
+        raise ValueError("compaction_replay_view_mismatch")
+    return [b for b in blocks if b["type"] not in {"thinking", "redacted_thinking"}]