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

ksadk/harness/native/adapters.py

@@ -0,0 +1,291 @@
+"""Explicit, host-injected bridges for native ports; no runtime SDK imports."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Awaitable, Callable, Sequence
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal, Protocol, TypeVar
+
+from pydantic import BaseModel, JsonValue
+
+from .effect_admission import check_effect_admission
+from .model import ModelImageContent, ModelTurnResult, from_reasoning_turn
+from .ports import ModelRequest, ToolDefinition, ToolRequest, ToolResult, digest
+from .state import RunScope
+from .tool_input_validation import ToolInputValidator
+
+if TYPE_CHECKING:
+    from ksadk.harness.reasoner import HarnessReasoningTurn
+
+ToolCallback = Callable[[ToolRequest], Awaitable[ToolResult]]
+AuthorizationResult = Literal["allow", "deny"] | ToolResult
+ToolAuthorizer = Callable[[ToolRequest], Awaitable[AuthorizationResult]]
+_Model = TypeVar("_Model", bound=BaseModel)
+
+
+def _encode(model: BaseModel) -> bytes:
+    return json.dumps(
+        model.model_dump(mode="python"),
+        ensure_ascii=False,
+        allow_nan=False,
+        separators=(",", ":"),
+    ).encode("utf-8")
+
+
+def _snapshot(model: _Model) -> _Model:
+    # Pydantic's frozen setting is shallow. Round-tripping detaches nested JSON
+    # and revalidates even objects created with model_construct/model_copy.
+    return type(model).model_validate_json(_encode(model))
+
+
+@dataclass(frozen=True)
+class ToolBinding:
+    """A trusted definition and callback supplied by the host, never the model.
+
+    The callback must return ToolResult explicitly and preserve operation_key
+    when delegating to a service with its own idempotency/receipt protocol.
+    """
+
+    definition: ToolDefinition
+    callback: ToolCallback
+
+
+@dataclass(frozen=True)
+class _RegisteredTool:
+    definition_digest: str
+    validator: ToolInputValidator
+    callback: ToolCallback
+
+
+class StrictToolExecutor:
+    """Validate scope, pinned definition, arguments and current policy per call.
+
+    Only the exact policy result ``allow`` permits execution. An authenticated
+    interaction is input to policy, never a permission bit interpreted here.
+    Direct callers receive bounded results. Native runtime requests explicitly
+    defer final shaping to its ArtifactPort-aware effect boundary so the full
+    result is still available for offload.
+    The Kernel owns operation receipts, fencing and effect timeouts.
+    """
+
+    def __init__(
+        self,
+        *,
+        scope: RunScope,
+        tools: Sequence[ToolBinding],
+        authorize: ToolAuthorizer | None = None,
+        max_result_bytes: int = 65536,
+        max_image_bytes: int = 8 * 1024 * 1024,
+    ) -> None:
+        if type(max_result_bytes) is not int or max_result_bytes < 256:
+            raise ValueError("max_result_bytes must be at least 256")
+        if type(max_image_bytes) is not int or max_image_bytes < 0:
+            raise ValueError("max_image_bytes must be a non-negative integer")
+        self._scope = _snapshot(scope)
+        self._authorize = authorize
+        self._max_result_bytes = max_result_bytes
+        self._max_image_bytes = max_image_bytes
+        self._tools: dict[str, _RegisteredTool] = {}
+        for binding in tools:
+            definition = _snapshot(binding.definition)
+            if not definition.name.strip() or not callable(binding.callback):
+                raise ValueError("tool binding requires a name and callable callback")
+            if definition.name in self._tools:
+                raise ValueError("duplicate tool definition")
+            validator = ToolInputValidator(definition.parameters)
+            self._tools[definition.name] = _RegisteredTool(
+                definition_digest=digest(definition),
+                validator=validator,
+                callback=binding.callback,
+            )
+
+    @staticmethod
+    def _error(code: str, *, uncertain: bool = False) -> ToolResult:
+        return ToolResult(status="uncertain" if uncertain else "error", content={"code": code})
+
+    def _bounded_result(self, result: ToolResult, request: ToolRequest) -> ToolResult:
+        result = _snapshot(result)
+        if request.result_delivery == "runtime_managed":
+            return result
+        images = tuple(
+            block for block in result.content_blocks if isinstance(block, ModelImageContent)
+        )
+        media_bytes = sum(len(_encode(image)) for image in images)
+        text_result = result.model_copy(
+            update={
+                "content_blocks": tuple(
+                    block
+                    for block in result.content_blocks
+                    if not isinstance(block, ModelImageContent)
+                )
+            }
+        )
+        payload = _encode(text_result)
+        media_overflow = media_bytes > self._max_image_bytes or len(images) > 8
+        if len(payload) > self._max_result_bytes or media_overflow:
+            return ToolResult(
+                status="uncertain" if result.status == "uncertain" else "error",
+                content={
+                    "code": "tool_media_too_large" if media_overflow else "tool_result_too_large",
+                    "original_bytes": media_bytes if media_overflow else len(payload),
+                    "limit_bytes": (
+                        self._max_image_bytes if media_overflow else self._max_result_bytes
+                    ),
+                    "execution_status": result.status,
+                    "retryability": "requires_reconcile",
+                },
+                resource_usage=result.resource_usage,
+                browser_session_ref=result.browser_session_ref,
+                browser_session_closed=result.browser_session_closed,
+            )
+        return result
+
+    async def execute(self, request: ToolRequest) -> ToolResult:
+        try:
+            sealed = _snapshot(request)
+        except Exception:
+            return self._error("invalid_tool_request")
+        if sealed.scope != self._scope:
+            return self._error("scope_mismatch")
+        if sealed.call.wire_arguments_invalid:
+            return self._error("malformed_tool_arguments")
+        binding = self._tools.get(sealed.call.name)
+        if binding is None:
+            return self._error("unknown_tool")
+        if digest(sealed.definition) != binding.definition_digest:
+            return self._error("definition_mismatch")
+        if rejection := binding.validator.rejection(sealed.call.arguments):
+            return ToolResult(status="error", content=rejection)
+        if self._authorize is None:
+            return self._error("policy_denied")
+        check_effect_admission()
+        try:
+            decision = await self._authorize(_snapshot(sealed))
+        except Exception:
+            return self._error("policy_error")
+        check_effect_admission()
+        if isinstance(decision, ToolResult) and decision.status == "approval_required":
+            try:
+                return self._bounded_result(decision, sealed)
+            except Exception:
+                return self._error("invalid_policy_decision")
+        if type(decision) is not str:
+            return self._error("invalid_policy_decision")
+        if decision == "deny":
+            return self._error("policy_denied")
+        if decision != "allow":
+            return self._error("invalid_policy_decision")
+        try:
+            callback_request = _snapshot(sealed)
+            check_effect_admission()
+            result = await binding.callback(callback_request)
+        except Exception as exc:
+            # The locked host definition is the effect authority. A callback
+            # declared read-only cannot leave a write to reconcile, so report
+            # a deterministic tool error the model can work around. Mutating
+            # callbacks remain uncertain because a write may have committed.
+            return ToolResult(
+                status="error" if sealed.definition.read_only else "uncertain",
+                content={
+                    "code": "callback_failed",
+                    "exception_type": type(exc).__name__,
+                },
+            )
+        if not isinstance(result, ToolResult):
+            return self._error(
+                "invalid_tool_result", uncertain=not sealed.definition.read_only
+            )
+        try:
+            return self._bounded_result(result, sealed)
+        except Exception:
+            return self._error(
+                "invalid_tool_result", uncertain=not sealed.definition.read_only
+            )
+
+
+@dataclass(frozen=True)
+class _LegacyToolSchema:
+    openai_schema: dict[str, object]
+
+
+class _LegacyReasoner(Protocol):
+    async def complete(self, **kwargs: object) -> HarnessReasoningTurn: ...
+
+
+def _project_messages(request: ModelRequest) -> list[dict[str, JsonValue]]:
+    from .model_replay import project_model_message
+    from .operator_guidance import operator_input_history_view
+    from .request_media import project_request_media
+
+    messages: list[dict[str, JsonValue]] = []
+    view = operator_input_history_view(request.messages, request.profile)
+    for source in project_request_media(view, request.profile, purpose=request.purpose):
+        messages.append(project_model_message(source, request.profile))
+    if request.instructions:
+        first = messages[0] if messages else {}
+        if first.get("role") != "system" or first.get("content") != request.instructions:
+            messages.insert(0, {"role": "system", "content": request.instructions})
+    from .operator_guidance import control_is_journaled
+
+    journaled = control_is_journaled(
+        request.messages, request.profile, request.instructions, request.turn_control,
+    ) if request.purpose == "task" else False
+    if request.turn_control is not None and not journaled:
+        messages.append(request.turn_control.message())
+    return messages
+
+
+class LegacyReasonerModelPort:
+    """Bridge a completed legacy reasoner using a host-pinned model and scope.
+
+    The legacy turn does not expose finish_reason or stream-completion metadata.
+    Their absence remains explicit in the mapped result; this adapter cannot
+    provide native provider conformance or recover a truncation hidden upstream.
+    Provider exceptions propagate to the Kernel without inventing retryability.
+    """
+
+    def __init__(
+        self,
+        reasoner: _LegacyReasoner,
+        *,
+        scope: RunScope,
+        model: str,
+        profile_digest: str,
+    ) -> None:
+        if not model.strip() or not profile_digest.strip():
+            raise ValueError("a host model mapping and profile digest are required")
+        if not callable(getattr(reasoner, "complete", None)):
+            raise ValueError("reasoner must expose complete")
+        self._reasoner = reasoner
+        self._scope = _snapshot(scope)
+        self._model = model
+        self._profile_digest = profile_digest
+
+    async def complete(self, request: ModelRequest) -> ModelTurnResult:
+        sealed = _snapshot(request)
+        if sealed.scope != self._scope:
+            raise ValueError("model request scope mismatch")
+        if sealed.profile.digest != self._profile_digest:
+            raise ValueError("model request profile mismatch")
+        tools = tuple(
+            _LegacyToolSchema(
+                openai_schema={
+                    "type": "function",
+                    "function": {
+                        "name": tool.name,
+                        "description": tool.description,
+                        "parameters": tool.parameters,
+                    },
+                }
+            )
+            for tool in sealed.tools
+        )
+        turn = await self._reasoner.complete(
+            model=self._model,
+            prompt=sealed.instructions,
+            messages=_project_messages(sealed),
+            tools=tools,
+            max_output_tokens=sealed.effective_max_output_tokens,
+        )
+        return from_reasoning_turn(turn, request_id=sealed.request_id, attempt_id=sealed.attempt_id)

ksadk/harness/native/artifact_contract.py

@@ -0,0 +1,14 @@
+"""Pure immutable artifact identity, shared by inputs and effect ports."""
+
+from pydantic import Field
+
+from .state import Contract
+
+
+class ArtifactRef(Contract):
+    """Opaque host-owned content reference; tool text cannot create one."""
+
+    uri: str = Field(min_length=1, max_length=2048, pattern=r"^artifact://\S+$")
+    content_hash: str = Field(pattern=r"^sha256:[0-9a-f]{64}$")
+    size_bytes: int = Field(strict=True, ge=0)
+    mime_type: str = Field(min_length=1, max_length=160, pattern=r"^[^\r\n]+$")

ksadk/harness/native/artifact_partial_read_capacity.py

@@ -0,0 +1,171 @@
+"""Pure admission of one executable ArtifactRead plus budget-refused suffix.
+
+The projected result is never a receipt or a Store fact. This limited quote
+assumes ordinary completion without intervening commands or host changes.
+"""
+
+from __future__ import annotations
+
+import json
+
+from .artifact_read_contract import ARTIFACT_READ_DEFINITION
+from .artifact_read_capacity import _declared_group
+from .context_artifact_page import artifact_page_observation
+from .context_runtime_contracts import CompactionHistory
+from .delivery_review import delivery_review_messages
+from .effective_configuration import effective_run_configuration
+from .machine import next_transition, reduce_tool
+from .ports import ToolResult, digest
+from .state import RunPhase
+from .tool_budget import model_instructions, model_tool_surface, model_turn_control
+from .transitions import commit_transition
+
+PARTIAL_ARTIFACT_CAPACITY_POLICY = "one-read-and-budget-refused-suffix/v1"
+
+
+def _valid_arguments(arguments):
+    return (
+        isinstance(arguments, dict)
+        and not set(arguments).difference({"uri", "offset_chars", "limit_chars"})
+        and isinstance(arguments.get("uri"), str)
+        and bool(arguments["uri"])
+        and type(arguments.get("offset_chars", 0)) is int
+        and arguments.get("offset_chars", 0) >= 0
+        and type(arguments.get("limit_chars", 16000)) is int
+        and 1 <= arguments.get("limit_chars", 16000) <= 32000
+    )
+
+
+def partial_artifact_group_admission(snapshot, configuration, driver):
+    """Return a pure result predicate only for exactly one executable call.
+
+    Every prior message and completed history remains in the projected state.
+    Actual native transitions generate all unexecuted suffix observations; no
+    arithmetic estimate or fabricated receipt stands in for their framing.
+    """
+    if (
+        snapshot.configuration_digest != configuration.digest
+        or snapshot.profile_digest != digest(configuration.profile)
+        or snapshot.context_binding != driver.binding
+    ):
+        raise ValueError("source_read_configuration_mismatch")
+    planner = driver.planner
+    if (
+        planner is None
+        or snapshot.phase != RunPhase.EXECUTING_TOOLS
+        or snapshot.force_compaction
+        or not snapshot.pending_intent
+        or len(snapshot.pending_tools) < 2
+        or snapshot.pending_intent != f"{snapshot.run_id}:effect:{snapshot.revision}"
+        or snapshot.revision < 1
+        or snapshot.event_seq < 1
+    ):
+        return None
+    group = _declared_group(snapshot)
+    if group is None:
+        return None
+    declared, _sealed = group
+    if len(declared["tool_calls"]) > planner.policy.read_working_set_count:
+        return None
+    arguments = [json.loads(c["function"]["arguments"]) for c in declared["tool_calls"]]
+    if not all(_valid_arguments(a) for a in arguments):
+        return None
+    config = effective_run_configuration(configuration, snapshot)
+    installed = [t for t in config.tools if t.name == ARTIFACT_READ_DEFINITION.name]
+    if (
+        len(installed) != 1
+        or installed[0].model_copy(update={"feedback_profile_digest": None})
+        != ARTIFACT_READ_DEFINITION
+        or config.limits.max_tool_calls - snapshot.tool_calls - snapshot.descendant_tool_calls != 1
+        or snapshot.model_calls + snapshot.descendant_model_calls >= config.limits.max_model_calls
+    ):
+        return None
+    current = snapshot.model_copy(deep=True)
+    before = current.model_copy(
+        update={
+            "revision": current.revision - 1,
+            "event_seq": current.event_seq - 1,
+            "pending_intent": None,
+        }
+    )
+    prepared = next_transition(before, config)
+    if (
+        prepared is None
+        or len(prepared.intents) != 1
+        or prepared.intents[0].kind != "tool"
+        or prepared.intents[0].operation_key != current.pending_intent
+        or prepared.intents[0].payload != {"call": current.pending_tools[0]}
+        or prepared.snapshot != current
+    ):
+        return None
+    call = current.pending_tools[0]
+    available = {r["uri"]: r for r in current.artifact_refs}
+    ref = available.get(call["arguments"]["uri"])
+    if ref is None:
+        return None
+
+    def admit(result):
+        if (
+            not isinstance(result, ToolResult)
+            or result.status not in {"ok", "error"}
+            or result != ToolResult(status=result.status, content=result.content)
+            or not isinstance(result.content, dict)
+        ):
+            return False
+        if result.status == "ok":
+            page = result.content
+            if any(page.get(k) != v for k, v in ref.items()) or not (
+                page.get("content") or page.get("complete") is True
+            ):
+                return False
+            message = {
+                "role": "tool",
+                "tool_call_id": call["call_id"],
+                "content": json.dumps({"status": "ok", "content": page}, ensure_ascii=False),
+            }
+            if artifact_page_observation(message, arguments=call["arguments"]) is None:
+                return False
+        elif result.content.get("code") != "artifact_page_budget_unavailable" or set(
+            result.content
+        ).difference({"code", "capacity_scope", "page_limits", "next_read_shape"}):
+            return False
+        updated = reduce_tool(current, result, definition=installed[0])
+        received = commit_transition(current, updated, "effect.received")
+        completed = next_transition(received.snapshot, config)
+        if (
+            completed is None
+            or completed.intents
+            or completed.snapshot.phase != RunPhase.PREPARING_CONTEXT
+            or len(completed.events) != 1
+            or completed.events[0].kind != "budget.exhausted"
+            or completed.snapshot.pending_tools
+            or completed.snapshot.tool_calls != current.tool_calls + 1
+            or completed.snapshot.model_calls != current.model_calls
+            or completed.snapshot.compaction_history != current.compaction_history
+            or completed.snapshot.messages[: len(current.messages)] != current.messages
+        ):
+            return False
+        projected = completed.snapshot
+        plan = planner.plan(
+            source_revision=projected.revision,
+            model_turn=projected.model_calls,
+            profile=config.profile,
+            instructions=model_instructions(projected, config),
+            tools=model_tool_surface(projected, config),
+            context_tools=config.tools,
+            messages=delivery_review_messages(projected),
+            continuity=driver.continuity(projected, config),
+            contract=config.contract,
+            history=CompactionHistory.model_validate(projected.compaction_history),
+            force_compaction=False,
+            turn_control=model_turn_control(projected, config),
+            allow_compaction=False,
+        )
+        return bool(
+            plan.action == "ready"
+            and plan.prepared is not None
+            and plan.prepared.counted_input_tokens + config.profile.max_output_tokens
+            <= config.profile.context_window
+        )
+
+    return admit

ksadk/harness/native/artifact_read_capacity.py

@@ -0,0 +1,182 @@
+"""Pure capacity estimates for a declared, canonical artifact read batch.
+
+Estimates are never receipts or facts. They apply only to ordinary completion
+of the current read-only group without intervening commands or host changes.
+The real ContextPlanner remains the hard admission authority after execution.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+
+from .artifact_read_contract import ARTIFACT_READ_DEFINITION
+from .effective_configuration import effective_run_configuration
+from .machine import next_transition, reduce_parallel_readonly_tools, reduce_tool
+from .model import ModelToolCall
+from .ports import ToolResult, digest
+from .state import RunPhase
+from .tool_budget import model_instructions, model_tool_surface, model_turn_control
+from .transitions import commit_transition
+
+ARTIFACT_CAPACITY_POLICY = "sealed-artifact-batch/v1"
+
+
+@dataclass(frozen=True)
+class ArtifactGroupCapacity:
+    """An estimate in the bound planner's units, not persistent execution state."""
+
+    source_units: int
+    result_message_units: int
+    fixed_tokens: int
+    summary_tokens: int
+    group_size: int
+
+
+def _declared_group(snapshot):
+    index = next((i for i in range(len(snapshot.messages)-1, -1, -1)
+                  if snapshot.messages[i].get("role") == "assistant"
+                  and snapshot.messages[i].get("tool_calls")), None)
+    if index is None:
+        return None
+    declared = snapshot.messages[index]
+    calls = declared["tool_calls"]
+    tail = snapshot.messages[index+1:]
+    if (not calls or len({c["id"] for c in calls}) != len(calls)
+            or len(tail) + len(snapshot.pending_tools) != len(calls)):
+        return None
+    try:
+        arguments = [json.loads(c["function"]["arguments"]) for c in calls]
+        # Duplicate requests can produce a separate loop-warning observation;
+        # their future framing is deliberately outside this bounded quote.
+        if len({json.dumps(a, sort_keys=True) for a in arguments}) != len(calls):
+            return None
+        if any(c["function"]["name"] != "ArtifactRead" for c in calls):
+            return None
+        if any(m.get("role") != "tool" or m.get("tool_call_id") != c["id"]
+               or m.get("receipt_goal_revision") != snapshot.goal_revision
+               or json.loads(m["content"]).get("status") != "ok"
+               for m, c in zip(tail, calls)):
+            return None
+        expected = tuple(ModelToolCall(call_id=c["id"], name=c["function"]["name"],
+                                       arguments=a).model_dump(mode="json")
+                         for c, a in zip(calls[len(tail):], arguments[len(tail):]))
+        if expected != snapshot.pending_tools:
+            return None
+        if len(calls) == 1:
+            previous = next((m for m in reversed(snapshot.messages[:index])
+                             if m.get("role") == "assistant" and m.get("tool_calls")), None)
+            if previous:
+                prior = previous["tool_calls"][-1]["function"]
+                if (prior["name"] == "ArtifactRead"
+                        and json.loads(prior["arguments"]) == arguments[0]):
+                    return None
+    except (KeyError, TypeError, ValueError):
+        return None
+    return declared, tail
+
+
+def artifact_group_capacity(snapshot, configuration, driver):
+    """Quote no-command batch completion using the same pure native reducers.
+
+    Receipts, progress digits, capped receipt digests, tool-budget controls and
+    real summary framing are remeasured rather than estimated by fixed magic
+    constants or by guessing the future operation-key revision width.
+    """
+    if (snapshot.configuration_digest != configuration.digest
+            or snapshot.profile_digest != digest(configuration.profile)
+            or snapshot.context_binding != driver.binding):
+        raise ValueError("source_read_configuration_mismatch")
+    planner = driver.planner
+    if (planner is None or not planner.policy.read_working_set_count
+            or snapshot.phase != RunPhase.EXECUTING_TOOLS):
+        return None
+    group = _declared_group(snapshot)
+    if group is None or not snapshot.pending_tools or not snapshot.pending_intent:
+        return None
+    declared, sealed = group
+    # The planner's retained-source count is a bound on source identities,
+    # not on the number of atomic call groups. The original declared count
+    # is a safe upper bound without pretending overlapping sources are new.
+    if len(declared["tool_calls"]) > planner.policy.read_working_set_count:
+        return None
+    config = effective_run_configuration(configuration, snapshot)
+
+    installed = [t for t in config.tools if t.name == ARTIFACT_READ_DEFINITION.name]
+    if (len(installed) != 1 or installed[0].model_copy(update={"feedback_profile_digest": None})
+            != ARTIFACT_READ_DEFINITION):
+        return None
+    if (snapshot.tool_calls + snapshot.descendant_tool_calls + len(snapshot.pending_tools)
+            > config.limits.max_tool_calls):
+        return None
+    # An intervening committed command breaks this finite no-command estimate.
+    # It must not be disguised by deriving new keys from an old pending intent.
+    if snapshot.pending_intent != f"{snapshot.run_id}:effect:{snapshot.revision}":
+        return None
+    current = snapshot.model_copy(deep=True)
+    first = True
+    remaining = len(snapshot.pending_tools)
+    while current.pending_tools:
+        before = (current.model_copy(update={"revision": current.revision-1,
+                                             "pending_intent": None}) if first else current)
+        prepared = next_transition(before, config)
+        if (prepared is None or not prepared.intents
+                or prepared.intents[0].kind != "tool"):
+            return None
+        intent = prepared.intents[0]
+        if first and intent.operation_key != current.pending_intent:
+            return None
+        current = prepared.snapshot
+        calls = intent.payload.get("calls") or [intent.payload["call"]]
+        # Only synthetic result shapes enter these detached reducers. The
+        # parent intent owns its child intents; never price them as separate
+        # tool groups or execute their ports while making this estimate.
+        results = [ToolResult(status="ok", content={"capacity_call": call["call_id"]})
+                   for call in calls]
+        if intent.payload.get("parallel_readonly") is True:
+            updated = reduce_parallel_readonly_tools(
+                current, ToolResult(status="ok", content={
+                    "batch_results": [result.model_dump(mode="json") for result in results],
+                }), calls, definitions=config.tools,
+            )
+        else:
+            updated = reduce_tool(current, results[0], definition=installed[0])
+        current = commit_transition(current, updated, "effect.received").snapshot
+        first = False
+    completed = next_transition(current, config)
+    if completed is None or completed.snapshot.phase != RunPhase.PREPARING_CONTEXT:
+        return None
+    current = completed.snapshot
+    fixed = []
+    # Novelty can advance anywhere from zero to the remaining call count. A
+    # real tokenizer need not assign monotonic costs across numeric digit runs.
+    for progress in range(snapshot.observed_progress_revision,
+                          snapshot.observed_progress_revision + remaining + 1):
+        projected = current.model_copy(update={"observed_progress_revision": progress})
+        fixed.append(planner.fixed_request_cost(
+            instructions=model_instructions(projected, config),
+            continuity=driver.continuity(projected, config), contract=config.contract,
+            tools=model_tool_surface(projected, config),
+            turn_control=model_turn_control(projected, config),
+        ))
+    profile = config.profile
+    def count(message):
+        return planner.count_model_message(message, profile)
+
+    goal = {"role": "user", "content": snapshot.goal}
+    # Existing sealed receipts are still in this original group. They cannot
+    # disappear from the denominator or be silently charged as older history.
+    size = len(declared["tool_calls"])
+    available = (profile.context_window - profile.max_output_tokens - max(fixed)
+                 - count(goal) - count(declared)
+                 - sum(count(m) for m in snapshot.messages if m.get("role") == "system"))
+    results = min(available - planner.summary_reservation(profile),
+                  planner.policy.read_working_set_max_tokens - count(declared),
+                  planner.policy.read_working_set_total_max_tokens - count(declared))
+    result_units = min(results // size,
+                       (results - sum(count(m) for m in sealed)) // remaining)
+    return ArtifactGroupCapacity(
+        source_units=available // 2 // size, result_message_units=result_units,
+        fixed_tokens=max(fixed), summary_tokens=planner.summary_reservation(profile),
+        group_size=size,
+    )

ksadk/harness/native/artifact_read_contract.py

@@ -0,0 +1,27 @@
+"""Pure, reserved host artifact-reader contract; no adapter or storage effects."""
+
+from .ports import ToolDefinition
+
+ARTIFACT_READ_NAME = "ArtifactRead"
+ARTIFACT_READ_DEFINITION = ToolDefinition(
+    name=ARTIFACT_READ_NAME,
+    description=(
+        "Read a bounded character page from a host-owned ArtifactRef supplied with user input "
+        "or returned by an earlier tool call in this session. Continue with next_offset_chars "
+        "until complete."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "uri": {"type": "string", "minLength": 1},
+            "offset_chars": {"type": "integer", "minimum": 0},
+            "limit_chars": {"type": "integer", "minimum": 1, "maximum": 32000},
+        },
+        "required": ["uri"],
+        "additionalProperties": False,
+    },
+    read_only=True,
+    concurrent_safe=True,
+    progress_observation=True,
+    context_role="artifact_read",
+)