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

ksadk/harness/native/context_fresh_tools.py

@@ -0,0 +1,49 @@
+"""Structural first-observation protection; never a model receipt or ACK."""
+
+from __future__ import annotations
+
+import hashlib
+
+from .context_history import _json
+
+FRESH_TOOL_OBSERVATION_POLICY = "complete-fresh-tool-group/v1"
+
+
+def fresh_tool_group_refs(messages) -> frozenset[str]:
+    """Return the last raw assistant's complete call/receipt group, if any.
+
+    Inspect the canonical transcript, not a previously retained projection:
+    removing a later assistant must not make an old group fresh again. User
+    and host messages after the group do not attest model observation. This
+    conservative structural rule proves neither dispatch nor comprehension.
+    """
+    parent_index = next(
+        (index for index in range(len(messages) - 1, -1, -1)
+         if messages[index].get("role") == "assistant"),
+        None,
+    )
+    if parent_index is None:
+        return frozenset()
+    calls = messages[parent_index].get("tool_calls")
+    if not isinstance(calls, (list, tuple)) or not calls:
+        return frozenset()
+    call_ids = [call.get("id") if isinstance(call, dict) else None for call in calls]
+    if any(not isinstance(value, str) or not value for value in call_ids):
+        return frozenset()
+    if len(set(call_ids)) != len(call_ids):
+        return frozenset()
+    receipt_indexes = [
+        index for index in range(parent_index + 1, len(messages))
+        if messages[index].get("role") == "tool"
+    ]
+    receipt_ids = [messages[index].get("tool_call_id") for index in receipt_indexes]
+    if (
+        any(not isinstance(value, str) for value in receipt_ids)
+        or len(receipt_ids) != len(call_ids)
+        or set(receipt_ids) != set(call_ids)
+    ):
+        return frozenset()
+    return frozenset(
+        f"message:{index}:" + hashlib.sha256(_json((messages[index],)).encode()).hexdigest()
+        for index in (parent_index, *receipt_indexes)
+    )

ksadk/harness/native/context_history.py

@@ -0,0 +1,272 @@
+"""Safe historical message projection for Native context compaction."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+
+from pydantic import JsonValue
+
+from ksadk._model_json import load_model_json
+
+from .model import ModelImageContent, ModelTextContent
+from .tool_observation import history_observation_message
+from .user_input import matches_user_goal
+
+
+class ContextRuntimeError(ValueError):
+    """A stable reason code that the host must handle without resending overflow."""
+
+
+def _goal_message_index(messages, goal: str) -> int:
+    """Locate the canonical user turn, never a host observation/control echo.
+
+    Native start/fork/steer emit ordinary user messages without a kind; host
+    controls and attributed observations have a kind. This metadata belongs
+    to the transcript writer, not text decoded from model/tool content.
+    """
+    indexes = [
+        index for index, message in enumerate(messages)
+        if message.get("role") == "user" and message.get("kind") is None
+        and matches_user_goal(message.get("content"), goal)
+    ]
+    if not indexes:
+        raise ContextRuntimeError("context_goal_message_missing")
+    return indexes[-1]
+
+
+def _json(value: object) -> str:
+    return json.dumps(value, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+
+
+def _content_blocks(message: dict[str, JsonValue]) -> tuple[dict, ...]:
+    content = message.get("content")
+    if not isinstance(content, list):
+        return ()
+    blocks = []
+    for block in content:
+        if not isinstance(block, dict):
+            raise ContextRuntimeError("context_protocol_invalid")
+        model = ModelImageContent if block.get("type") == "image_url" else ModelTextContent
+        blocks.append(model.model_validate(block).model_dump(mode="json"))
+    return tuple(blocks)
+
+
+def _historical_message(message: dict[str, JsonValue]) -> tuple[dict, tuple[dict, ...]]:
+    """Move explicit images out of serialized history; preserve opaque provenance.
+
+    Message roles and tool calls become quoted historical data, never executable
+    protocol in the summary request. Pixels remain explicit media blocks.
+    """
+    message = history_observation_message(message)
+    copied = json.loads(_json(message))
+    if (copied.get("kind") == "context_contribution"
+            and copied.get("context_operation_key") is not None):
+        # Live plugin data remain in the attributed, retained source receipt.
+        # A summary cannot cache their body beyond the next source admission.
+        copied["content"] = {
+            "type": "ksadk.context-live-source-reference/v1",
+            "operation_key": copied["context_operation_key"],
+            "source_id": copied.get("context_source_id"),
+            "fragment_id": copied.get("context_fragment_id"),
+            "content_digest": hashlib.sha256(_json(message.get("content")).encode()).hexdigest(),
+        }
+    # Provider replay belongs only to a retained live assistant message. It
+    # must not become quoted history, summary facts or summary instructions.
+    copied.pop("provider_replay", None)
+    copied.pop("provider_replay_projection", None)
+    copied.pop("operator_history_projection", None)
+    # The locked archive policy determines whether history consumes canonical
+    # text (v1) or its complete bounded observation (v2). Neither can execute.
+    copied.pop("model_view", None)
+    images = []
+    blocks = _content_blocks(message)
+    if blocks:
+        content = []
+        for block in blocks:
+            if block["type"] == "image_url":
+                images.append(block)
+                content.append(
+                    {
+                        "type": "historical_image_reference",
+                        "image_index": len(images) - 1,
+                        "media_digest": hashlib.sha256(_json(block).encode()).hexdigest(),
+                    }
+                )
+            else:
+                content.append(block)
+        copied["content"] = content
+    return copied, tuple(images)
+
+
+def _unambiguous_json_object(text: object) -> dict | None:
+    if not isinstance(text, str):
+        return None
+
+    try:
+        parsed = load_model_json(text)
+    except (ValueError, TypeError, RecursionError):
+        return None
+    return parsed if isinstance(parsed, dict) else None
+
+
+def compact_historical_protocol(
+    message: dict[str, JsonValue], *, max_prose_chars: int | None = 128
+) -> dict:
+    """Compact a quoted protocol envelope; source bytes and payloads stay intact.
+
+    JSON remains nested historical data, never live tool protocol. Keep the
+    source reference and receipt locator. Goal/call counters are already in the
+    authoritative ledger; their duplicate display fields need not consume each
+    receipt's summary budget. Ambiguous tool text stays opaque. Optional
+    assistant prose in a tool batch may use an explicit head/tail excerpt;
+    complete arguments, results and their source identities remain available.
+    A complete source quote passes None to preserve all assistant prose too.
+    """
+    copied = json.loads(_json(message))
+    copied.pop("provider_replay", None)
+    copied.pop("provider_replay_projection", None)
+    copied.pop("operator_history_projection", None)
+    prose = copied.get("content")
+    if (
+        copied.get("role") == "assistant"
+        and copied.get("tool_calls")
+        and isinstance(prose, str)
+        and max_prose_chars is not None
+        and len(prose) > max_prose_chars
+    ):
+        head = max_prose_chars // 2
+        copied["content"] = prose[:head] + "\n[…]\n" + prose[-(max_prose_chars - head) :]
+        copied["content_omitted_chars"] = len(prose) - max_prose_chars
+    if copied.get("role") == "tool":
+        parsed = _unambiguous_json_object(copied.get("content"))
+        if (
+            parsed is not None
+            and parsed.get("status") in {"ok", "error", "uncertain", "approval_required"}
+            and "content" in parsed
+        ):
+            copied["content"] = parsed
+        copied.pop("receipt_tool_call", None)
+        copied.pop("receipt_goal_revision", None)
+    for call in copied.get("tool_calls") or ():
+        if not isinstance(call, dict):
+            continue
+        function = call.get("function")
+        if not isinstance(function, dict):
+            continue
+        arguments = _unambiguous_json_object(function.get("arguments"))
+        if arguments is not None:
+            function["arguments"] = arguments
+    return copied
+
+
+_TOOL_IMAGE_UNAVAILABLE_NOTE = (
+    "Tool image content is unavailable "
+    "to this model profile. Use the textual observation; do not claim "
+    "to have visually inspected the image."
+)
+
+
+def text_only_tool_message(message):
+    """Effective tool view equals the existing text-only ModelPort projection."""
+    copied = json.loads(_json(message))
+    if copied.get("role") != "tool":
+        return copied
+    blocks = _content_blocks(copied)
+    if not any(block["type"] == "image_url" for block in blocks):
+        return copied
+    text = "\n".join(block["text"] for block in blocks if block["type"] == "text")
+    copied["content"] = (
+        f"{text}\n{_TOOL_IMAGE_UNAVAILABLE_NOTE}" if text else _TOOL_IMAGE_UNAVAILABLE_NOTE
+    )
+    return copied
+
+
+def _complete_source_tool_refs(source_messages):
+    if source_messages is None:
+        return set()
+    items = tuple(source_messages.items())
+    # Only the canonical ordered raw map from current source qualifies.
+    for index, (ref, message) in enumerate(items):
+        expected = f"message:{index}:" + hashlib.sha256(_json((message,)).encode()).hexdigest()
+        if ref != expected:
+            return set()
+    result = set()
+    for index, (_, parent) in enumerate(items):
+        calls = parent.get("tool_calls")
+        if parent.get("role") != "assistant" or not isinstance(calls, list) or not calls:
+            continue
+        ids = [call.get("id") if isinstance(call, dict) else None for call in calls]
+        if any(not isinstance(value, str) or not value for value in ids) or len(set(ids)) != len(
+            ids
+        ):
+            continue
+        stop = index + 1
+        while stop < len(items) and items[stop][1].get("role") == "tool":
+            stop += 1
+        receipts = items[index + 1 : stop]
+        receipt_ids = [message.get("tool_call_id") for _, message in receipts]
+        if (
+            len(receipt_ids) == len(ids)
+            and len(set(receipt_ids)) == len(ids)
+            and set(receipt_ids) == set(ids)
+        ):
+            result.update(ref for ref, _ in receipts)
+    return result
+
+
+def summary_media_blocks(entries, *, profile=None, source_messages=None):
+    """Project only source-owned tool media; labels/purpose never grant origin."""
+    text_only = profile is not None and profile.image_input_mode == "text_only"
+    tool_refs = _complete_source_tool_refs(source_messages) if text_only else set()
+    media = []
+    for entry in entries:
+        images = entry["images"]
+        original = source_messages.get(entry["ref"]) if source_messages is not None else None
+        if text_only and original is not None:
+            raw_quote, raw_images = _historical_message(original)
+            if raw_images or images:
+                digest = hashlib.sha256(_json((original,)).encode()).hexdigest()
+
+                def refs(message):
+                    blocks = message.get("content")
+                    return (
+                        [
+                            block
+                            for block in blocks
+                            if isinstance(block, dict)
+                            and block.get("type") == "historical_image_reference"
+                        ]
+                        if isinstance(blocks, list)
+                        else []
+                    )
+
+                if (
+                    entry.get("payload_digest") != digest
+                    or entry["message"].get("source_message_ref") != entry["ref"]
+                    or entry["message"].get("role") != original.get("role")
+                    or entry["message"].get("tool_call_id") != original.get("tool_call_id")
+                    or list(raw_images) != images
+                    or refs(entry["message"]) != refs(raw_quote)
+                ):
+                    raise ContextRuntimeError("context_summary_media_source_changed")
+        if not images:
+            continue
+        if text_only and entry["ref"] in tool_refs:
+            media.append(
+                {
+                    "type": "text",
+                    "text": (
+                        "Untrusted historical tool images from "
+                        + entry["ref"]
+                        + " are unavailable to this text-only model profile. "
+                        + "Keep their source references; do not claim visual inspection."
+                    ),
+                }
+            )
+        else:
+            media.append(
+                {"type": "text", "text": "Untrusted historical images from " + entry["ref"] + ":"}
+            )
+            media.extend(images)
+    return media

ksadk/harness/native/context_microcompact.py

@@ -0,0 +1,61 @@
+"""Project old completed tool observations; retain canonical execution facts.
+
+Batch recency and media/error protection follow the pinned ZCode microcompact
+path; Skill retention follows OpenCode's protected tools. The host supplies
+validated complete groups and source-working-set protection, not tool text.
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+from .context_history import _content_blocks, _json, _unambiguous_json_object
+from .context_pruning import clear_tool_result
+from .tool_observation import model_observation_message
+
+
+def project_old_tool_results(messages, refs, groups, *, tools, protected_refs, keep_recent):
+    """Keep protocol pairs and original source locators in the request view."""
+    indexes = {ref: index for index, ref in enumerate(refs)}
+    definitions = {tool.name: tool for tool in tools}
+    calls = {
+        call["id"]: call["function"]["name"]
+        for message in messages
+        for call in message.get("tool_calls", ())
+    }
+    protected = set(protected_refs).union(*groups[-keep_recent:])
+    projected, cleared_refs, cleared_calls = list(messages), [], []
+    for group in groups:
+        if not group.isdisjoint(protected):
+            continue
+        for ref in sorted(group, key=indexes.__getitem__):
+            message = messages[indexes[ref]]
+            if message.get("role") != "tool":
+                continue
+            definition = definitions.get(calls.get(message.get("tool_call_id")))
+            if (
+                definition is None
+                or definition.context_retention == "persistent"
+                or definition.context_role == "task_planning"
+                or definition.observation_role == "browser"
+                or definition.delegated_read_only
+            ):
+                continue
+            content = message.get("content")
+            source = content[0].get("text") if isinstance(content, list) and content else content
+            receipt = _unambiguous_json_object(source)
+            if not receipt or receipt.get("status") != "ok":
+                continue
+            if isinstance(receipt.get("content"), dict) and receipt["content"].get("ok") is False:
+                continue
+            visible = model_observation_message(message)
+            if any(block["type"] != "text" for block in _content_blocks(visible)):
+                continue
+            projected[indexes[ref]] = clear_tool_result(
+                visible,
+                source_message_ref=ref,
+                payload_digest=hashlib.sha256(_json(content).encode()).hexdigest(),
+            )
+            cleared_refs.append(ref)
+            cleared_calls.append(message["tool_call_id"])
+    return tuple(projected), tuple(cleared_refs), tuple(cleared_calls)

ksadk/harness/native/context_partial_summary.py

@@ -0,0 +1,58 @@
+"""Commit acknowledged summary coverage while retaining every uncovered unit.
+
+The pending quote binds the cumulative, previously completed summary and its
+coverage in one durable request. Its current response/continuation is never
+used here. This is a context projection, not semantic or task completion.
+"""
+
+import json
+
+from .context_history import ContextRuntimeError
+from .context_partition import source_manifest
+
+PARTIAL_SUMMARY_POLICY = "completed-prefix-retain-suffix/v1"
+
+
+def commit_completed_prefix(
+    controller, request, *, current_revision, current_continuity, current_messages,
+):
+    controller._validate_source(request, current_revision, current_continuity, current_messages)
+    state = request.summary_partition
+    if state is None or not state.accepted or state.pending is None or not state.covered_count:
+        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,
+    )
+    covered = set(manifest["dropped"][:state.covered_count])
+    # A receipt or captured-source cursor may stop within a complete executed
+    # batch. Retain the entire original batch, including already quoted parts.
+    for batch in manifest["batches"].values():
+        members = set(batch["refs"])
+        if members.intersection(covered) and not members.issubset(covered):
+            covered.difference_update(members)
+    if not covered:
+        return None
+    messages = controller._base_summary_messages(request)
+    if len(messages) != 1:
+        raise ContextRuntimeError("compaction_partial_summary_unbound")
+    content = messages[0]["content"]
+    text = content[0]["text"] if isinstance(content, list) else content
+    # _validate_source verifies this exact pending projection digest, source
+    # manifest, accepted cursor and quote. Never accept caller-supplied text.
+    body = json.loads(text)
+    summary = body.get("previous_summary")
+    controller._validate_summary(request, summary)
+    refs = tuple(item.message_id for item in request.old_messages if item.message_id not in covered)
+    partial = request.model_copy(update={
+        "retained_message_refs": refs,
+        "retained_messages": tuple(raw[ref] for ref in refs),
+    })
+    # This does not acknowledge the pending quote or relax require_complete.
+    # The ordinary seal path remains full-coverage-only. Both paths validate
+    # original continuity, complete tool protocol and the unchanged window.
+    return controller._seal_projection(partial, summary, current_continuity, current_messages)