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

ksadk/harness/native/context_source_fragments.py

@@ -0,0 +1,188 @@
+"""Pure quotation of contiguous text from already-executed source captures.
+
+A source slice is historical data, never a new tool execution or live result.
+The caller supplies a locked reader name; byte/coverage identities bind the
+quoted range to the canonical receipt rather than trusting tool prose.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+
+from pydantic import Field
+
+from .context_artifact_page import artifact_page_observation
+from .context_history import ContextRuntimeError, _unambiguous_json_object
+from .state import Contract
+from .tool_observation import model_observation_message
+
+SOURCE_FRAGMENT_POLICY = "captured-source-fragments/v1"
+FRESH_TEXT_FRAGMENT_POLICY = "quoted-fresh-tool-text/v1"
+
+
+class SourceTextPart(Contract):
+    source_ref: str
+    source_text_digest: str = Field(pattern=r"^[0-9a-f]{64}$")
+    start_chars: int = Field(strict=True, ge=0)
+    stop_chars: int = Field(strict=True, ge=1)
+    total_chars: int = Field(strict=True, ge=1)
+    chunk_index: int = Field(strict=True, ge=1)
+
+
+def captured_source(message, arguments):
+    if artifact_page_observation(message, arguments=arguments) is not None:
+        return _unambiguous_json_object(message["content"])["content"]["content"] or None
+    if message.get("role") != "tool" or "model_view" not in message:
+        return None
+    model_observation_message(message)  # Detect inconsistent persisted views.
+    receipt = _unambiguous_json_object(message.get("content"))
+    source = receipt.get("content") if receipt and receipt.get("status") == "ok" else None
+    if not isinstance(source, dict) or source.get("ok") is not True:
+        return None
+    carrier = source.get("requested_source")
+    if not isinstance(carrier, dict) or not isinstance(arguments, dict):
+        return None
+    path, body, span = (carrier.get(k) for k in ("path", "content", "read_range"))
+    if (
+        not isinstance(path, str) or not path or path != source.get("path")
+        or path != arguments.get("path") or not isinstance(body, str) or not body
+        or not isinstance(span, dict) or set(span) != {"start", "end"}
+        or any(type(v) is not int for v in span.values())
+        or type(source.get("total_lines")) is not int
+        or not 1 <= span["start"] <= span["end"] <= source["total_lines"]
+        or len(body.split("\n")) != span["end"] - span["start"] + 1
+    ):
+        return None
+    # Numbered and unnumbered captures share exact character coordinates.
+    # No source lines are selected by their semantic content.
+    return body
+
+
+def text_digest(body):
+    return hashlib.sha256(body.encode("utf-8")).hexdigest()
+
+
+def source_text_carrier(entry, capture):
+    """Find only the host-manifest's declared source field in quoted data."""
+    field = capture.get("source_field", "content.requested_source.content")
+    if field not in {"content.requested_source.content", "content.content", "content"}:
+        raise ContextRuntimeError("compaction_source_fragment_identity_changed")
+    carrier = entry["message"] if field == "content" else entry["message"]["content"]
+    pieces = field.split(".")
+    for key in pieces[:-1]:
+        carrier = carrier[key]
+    return carrier, pieces[-1]
+
+
+def accepted_batch_parent_reference(parent, assistant_ref, source_batch_digest):
+    """Refer to the already-accepted full parent without repeating its prose."""
+    return {
+        **parent,
+        "message": {
+            "role": "assistant", "source_message_ref": assistant_ref,
+            "kind": "previously_quoted_tool_batch_parent",
+            "source_batch_digest": source_batch_digest,
+            "content": None,
+        },
+    }
+
+
+def source_part_view(unit, state, manifest, plan, parts):
+    """Rebuild a quote from canonical data and explicit ordered source parts."""
+    batch = manifest["batches"][plan.assistant_ref]
+    if tuple(entry["ref"] for entry in unit) != batch["refs"] or not parts:
+        raise ContextRuntimeError("compaction_source_fragment_invalid")
+    parent_index = manifest["dropped"].index(plan.assistant_ref)
+    offset = max(0, state.covered_count - parent_index - 1)
+    refs = batch["receipt_refs"][offset : offset + len(parts)]
+    if tuple(part.source_ref for part in parts) != refs:
+        raise ContextRuntimeError("compaction_source_fragment_selection_changed")
+    parent = unit[0]
+    if state.covered_count > parent_index:
+        # The first accepted source quote already consumed the complete
+        # assistant parent. Repeat its canonical reference, rather than its
+        # prose and every call's arguments in each subsequent text piece.
+        # This marker is historical data, never live assistant/tool protocol.
+        parent = accepted_batch_parent_reference(
+            parent, plan.assistant_ref, batch["source_batch_digest"]
+        )
+    selected, covered = [parent], []
+    if state.covered_count == parent_index:
+        covered.append(plan.assistant_ref)
+    for index, (ref, part) in enumerate(zip(refs, parts)):
+        capture = manifest.get("source_captures", {}).get(ref)
+        if (
+            capture is None or part.source_text_digest != capture["text_digest"]
+            or part.total_chars != capture["total_chars"]
+            or not part.start_chars < part.stop_chars <= part.total_chars
+        ):
+            raise ContextRuntimeError("compaction_source_fragment_identity_changed")
+        previous = [p for p in state.source_parts if p.source_ref == ref]
+        expected_start = previous[-1].stop_chars if previous else 0
+        if part.start_chars != expected_start:
+            raise ContextRuntimeError("compaction_source_fragment_gap_or_overlap")
+        entry = json.loads(json.dumps(unit[1 + offset + index], ensure_ascii=False))
+        carrier, field = source_text_carrier(entry, capture)
+        body = carrier[field]
+        if text_digest(body) != part.source_text_digest:
+            raise ContextRuntimeError("compaction_source_fragment_identity_changed")
+        carrier[field] = body[part.start_chars : part.stop_chars]
+        selected.append(entry)
+        if part.stop_chars == part.total_chars:
+            covered.append(ref)
+        elif index != len(parts) - 1:
+            raise ContextRuntimeError("compaction_source_fragment_nonfinal_partial")
+    frame = {
+        "schema": "quoted-completed-source-fragments/v1",
+        "source_batch_digest": batch["source_batch_digest"],
+        "source_assistant_ref": plan.assistant_ref,
+        "call_ids": batch["call_ids"],
+        "source_parts": [part.model_dump(mode="json") for part in parts],
+        "source_field": "content.requested_source.content",
+        "excluded_receipts_are_already_executed": True,
+        "partial_text_is_not_a_new_tool_result": True,
+    }
+    if any(manifest["source_captures"][part.source_ref].get("source_field") for part in parts):
+        frame.pop("source_field")
+        frame.update(
+            schema="quoted-completed-source-fragments/v2",
+            source_fields=[{
+                "source_ref": part.source_ref,
+                "field": manifest["source_captures"][part.source_ref].get(
+                    "source_field", "content.requested_source.content"
+                ),
+            } for part in parts],
+        )
+    last = parts[-1]
+    complete = refs[-1] == batch["receipt_refs"][-1] and last.stop_chars == last.total_chars
+    return tuple(selected), frame, tuple(covered), complete
+
+
+def validate_source_parts(state, manifest):
+    """Check every acknowledged/pending range against its original source."""
+    if (state.source_parts or state.pending_source_parts) and (
+        state.source_fragment_policy != SOURCE_FRAGMENT_POLICY
+    ):
+        raise ContextRuntimeError("compaction_source_fragment_policy_changed")
+    positions = {}
+    chunks = {entry.chunk_index for entry in state.accepted}
+    for pending, parts in (
+        (False, state.source_parts), (True, state.pending_source_parts),
+    ):
+        for part in parts:
+            capture = manifest.get("source_captures", {}).get(part.source_ref)
+            if (
+                capture is None or part.source_text_digest != capture["text_digest"]
+                or part.total_chars != capture["total_chars"]
+                or part.start_chars != positions.get(part.source_ref, 0)
+                or not part.start_chars < part.stop_chars <= part.total_chars
+                or (not pending and part.chunk_index not in chunks)
+                or (pending and (state.pending is None
+                                 or part.chunk_index != state.pending.chunk_index))
+            ):
+                raise ContextRuntimeError("compaction_source_fragment_gap_or_overlap")
+            positions[part.source_ref] = part.stop_chars
+    for ref in manifest["dropped"][: state.covered_count]:
+        if ref in positions and positions[ref] != manifest["source_captures"][ref]["total_chars"]:
+            raise ContextRuntimeError("compaction_source_fragment_incomplete")

ksadk/harness/native/context_source_progress.py

@@ -0,0 +1,119 @@
+"""Derive source navigation from canonical, host-labeled tool messages.
+
+Only a host-granted workspace reader may supply the range protocol. Its data
+is an observation, not semantic coverage or a fresh authorization to edit.
+No disk reads, model calls or parsing of compaction prose occurs here.
+"""
+
+import hashlib
+import json
+
+from .context import SourceReadProgress
+from .context_pruning import project_workspace_read_result
+from .ports import ToolDefinition
+from .state import RunSnapshot
+
+
+def _range(source):
+    start, end, total, count = (
+        source.get(k) for k in ("start_line", "end_line", "total_lines", "line_count")
+    )
+    declared = source.get("read_range")
+    if (
+        any(type(v) is not int for v in (start, end, total, count))
+        or not 1 <= start <= end <= total
+        or count != end - start + 1
+        or not isinstance(declared, dict)
+        or any(type(declared.get(k)) is not int for k in ("start", "end"))
+        or declared != {"start": start, "end": end}
+        or not isinstance(source.get("content"), str)
+        or len(source["content"].split("\n")) != count
+    ):
+        return None
+    return start, end
+
+
+def source_read_progress(
+    snapshot: RunSnapshot, tools: tuple[ToolDefinition, ...], *, max_chars: int | None
+) -> tuple[SourceReadProgress, ...]:
+    names = {t.name for t in tools if t.read_only and t.context_role == "workspace_read"}
+    calls, progress = {}, {}
+    for message in snapshot.messages:
+        if message.get("role") == "assistant":
+            # A result must belong to the preceding declared tool group.
+            calls = {}
+            for call in message.get("tool_calls") or ():
+                try:
+                    if call["function"]["name"] in names:
+                        args = json.loads(call["function"]["arguments"])
+                        path = args.get("path")
+                        if isinstance(path, str) and path.strip() and len(path) <= 2048:
+                            calls[call["id"]] = path
+                except (ValueError, TypeError, KeyError, AttributeError):
+                    continue
+            continue
+        if message.get("role") != "tool":
+            continue
+        call_id = message.get("tool_call_id")
+        path = calls.get(call_id)
+        ref, cursor = message.get("receipt_ref"), message.get("receipt_tool_call")
+        if (
+            not path
+            or not isinstance(ref, str)
+            or not ref.startswith(f"{snapshot.run_id}:effect:")
+            or type(cursor) is not int
+            or not 0 < cursor <= snapshot.tool_calls
+                or type(message.get("receipt_goal_revision")) is not int
+                or message.get("receipt_goal_revision") != snapshot.goal_revision
+            or not isinstance(message.get("content"), str)
+        ):
+            continue
+        try:
+            receipt = json.loads(message["content"])
+            source = receipt.get("content")
+            if (
+                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)
+            ):
+                continue
+            returned = _range(source)
+            if returned is None:
+                continue
+            view = (
+                project_workspace_read_result(message, path=path, max_chars=max_chars)
+                if max_chars is not None
+                else message
+            )
+            if view is None:
+                continue
+            visible = json.loads(view["content"])["content"]
+            main = _range(visible) if isinstance(visible.get("content"), str) else None
+            item = SourceReadProgress(
+                path=path,
+                receipt_ref=ref,
+                tool_call_id=call_id,
+                returned_lines=returned,
+                configured_prefix_lines=main,
+                configured_next_start_line=(
+                    main[1] + 1 if main and main[1] < source["total_lines"] else None
+                ),
+                total_lines=source["total_lines"],
+                source_mtime_ns=(
+                    source.get("mtime_ns") if type(source.get("mtime_ns")) is int else None
+                ),
+                source_size_bytes=(
+                    source.get("size_bytes") if type(source.get("size_bytes")) is int else None
+                ),
+                source_payload_digest="sha256:"
+                + hashlib.sha256(source["content"].encode("utf-8")).hexdigest(),
+            )
+        except (ValueError, TypeError, KeyError, AttributeError):
+            continue
+        # Keep the latest successful page per exact path, never merge ranges
+        # across file versions or claim all intermediate lines were observed.
+        progress.pop(path, None)
+        progress[path] = item
+    return tuple(progress.values())