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

ksadk/harness/native/stop_hook_runtime.py

@@ -0,0 +1,151 @@
+"""Durable Stop proposals before final verification, without completion grants."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+from pydantic import Field, JsonValue
+
+from .completion_text import candidate_model_message
+from .hook_runtime_contract import (
+    HookInvocationRequest,
+    HookInvocationResult,
+    _json_bytes,
+    validate_hook_result,
+)
+from .state import Contract, RunPhase, RunSnapshot, move
+from .transitions import finish, prepare_effect
+
+if TYPE_CHECKING:
+    from .ports import RunConfiguration
+
+
+class StopHookState(Contract):
+    goal_revision: int = Field(strict=True, ge=0)
+    candidate_id: str | None = None
+    next_hook_index: int = Field(default=0, strict=True, ge=0)
+    continuation_count: int = Field(default=0, strict=True, ge=0)
+    feedback: tuple[dict[str, JsonValue], ...] = ()
+
+
+def stop_hook_state(snapshot: RunSnapshot) -> StopHookState:
+    if snapshot.stop_hook_state is not None:
+        state = StopHookState.model_validate_json(_json_bytes(snapshot.stop_hook_state))
+        if state.goal_revision == snapshot.goal_revision:
+            return state
+    return StopHookState(goal_revision=snapshot.goal_revision)
+
+
+def hook_feedback_messages(snapshot: RunSnapshot, messages: tuple[dict, ...]) -> tuple[dict, ...]:
+    """Reproject pending feedback before context budgeting, even after pruning."""
+    state = stop_hook_state(snapshot)
+    seen = {message.get("hook_operation_key") for message in messages}
+    return (*messages, *(item for item in state.feedback
+                         if item["hook_operation_key"] not in seen))
+
+
+def stop_hook_request(
+    snapshot: RunSnapshot, config: RunConfiguration, operation_key: str,
+) -> HookInvocationRequest:
+    candidate = snapshot.candidate or {}
+    if (snapshot.phase != RunPhase.VERIFYING or candidate.get("purpose") == "checkpoint"
+            or not candidate.get("candidate_id") or "final_text" not in candidate):
+        raise ValueError("Stop requires a final completion candidate")
+    state = stop_hook_state(snapshot)
+    index = state.next_hook_index if state.candidate_id == candidate["candidate_id"] else 0
+    hooks = tuple(hook for hook in config.hooks if "Stop" in hook.events)
+    if index >= len(hooks):
+        raise ValueError("no pending Stop Hook")
+    return HookInvocationRequest(
+        scope=snapshot.scope, run_id=snapshot.run_id, session_id=snapshot.session_id,
+        turn_id=snapshot.turn_id, operation_key=operation_key,
+        goal_revision=snapshot.goal_revision, goal=snapshot.goal,
+        tool_call_count=snapshot.tool_calls, stop_continuation_count=state.continuation_count,
+        event="Stop", definition=hooks[index],
+        candidate_id=candidate["candidate_id"], candidate_text=candidate["final_text"],
+    )
+
+
+def prepare_stop_hook(snapshot: RunSnapshot, config: RunConfiguration):
+    candidate = snapshot.candidate or {}
+    if (snapshot.phase != RunPhase.VERIFYING or snapshot.browser_reobservation_required
+            or candidate.get("purpose") == "checkpoint"):
+        return None
+    hooks = tuple(hook for hook in config.hooks if "Stop" in hook.events)
+    if not hooks:
+        return None
+    state = stop_hook_state(snapshot)
+    index = state.next_hook_index if state.candidate_id == candidate.get("candidate_id") else 0
+    if index >= len(hooks):
+        return None
+    key = f"{snapshot.run_id}:effect:{snapshot.revision + 1}"
+    request = stop_hook_request(snapshot, config, key)
+    return prepare_effect(snapshot, "hook", {"request": request.model_dump(mode="json")})
+
+
+def reduce_stop_hook(
+    snapshot: RunSnapshot, config: RunConfiguration, operation_key: str, result: dict,
+) -> RunSnapshot:
+    request = stop_hook_request(snapshot, config, operation_key)
+    result = validate_hook_result(request, HookInvocationResult.model_validate(result))
+    state = stop_hook_state(snapshot)
+    index = state.next_hook_index if state.candidate_id == request.candidate_id else 0
+    state = state.model_copy(update={"candidate_id": request.candidate_id,
+                                    "next_hook_index": index + 1})
+    updated = snapshot.model_copy(update={"pending_intent": None})
+    if result.status == "uncertain" or result.reason == "binding_unavailable":
+        return finish(updated.model_copy(update={"candidate": None}),
+                      "unverified", "effect_outcome_unknown")
+    if result.status == "failed":
+        optional_failure = result.reason in {
+            "producer_failed", "producer_invalid", "producer_timeout",
+            "input_budget_exceeded", "output_budget_exceeded",
+        }
+        if not optional_failure or request.definition.failure_mode != "warn":
+            return finish(updated.model_copy(update={"candidate": None}),
+                          "blocked", "hook_" + result.reason)
+    else:
+        output = result.output
+        if output.action == "deny":
+            return finish(updated.model_copy(update={"candidate": None}),
+                          "blocked", "stop_hook_denied")
+        if output.additional_context or output.action == "repair":
+            message = {
+                "role": "user", "kind": "hook_context", "hook_operation_key": operation_key,
+                "hook_goal_revision": snapshot.goal_revision,
+                "content": json.dumps({
+                    "event": "Stop", "hook_id": request.definition.hook_id,
+                    "source_ref": request.definition.source_ref,
+                    "binding_digest": request.definition.binding_digest,
+                    "action": output.action,
+                    "candidate_status": "rejected" if output.action == "repair" else "unverified",
+                    "data": output.additional_context,
+                }, ensure_ascii=False, sort_keys=True),
+            }
+            state = state.model_copy(update={"feedback": (*state.feedback, message)})
+            updated = updated.model_copy(update={"messages": (*updated.messages, message)})
+        if not request.definition.read_only:
+            updated = updated.model_copy(update={"workspace_observation_cursor": None})
+        if output.action == "repair":
+            limit = config.hook_stop_continuation_limit
+            if limit is None or state.continuation_count >= limit:
+                return finish(updated.model_copy(update={"candidate": None}),
+                              "blocked", "stop_hook_continuation_limit")
+            state = state.model_copy(update={
+                "candidate_id": None, "next_hook_index": 0,
+                "continuation_count": state.continuation_count + 1,
+            })
+            updated = move(updated, RunPhase.PREPARING_CONTEXT).model_copy(update={
+                "messages": (
+                    *snapshot.messages,
+                    candidate_model_message(snapshot),
+                    *updated.messages[len(snapshot.messages):],
+                ),
+                "candidate": None, "candidate_replay": None, "prepared_context": None,
+                "verification": None, "verification_tool_calls": None, "delivery_review": None,
+                # A Hook repair asks for a new answer, not the rejected
+                # candidate's suffix. Its separate Stop cap remains charged.
+                "continuations": 0,
+            })
+    return updated.model_copy(update={"stop_hook_state": state.model_dump(mode="json")})

ksadk/harness/native/studio_admission.py

@@ -0,0 +1,29 @@
+"""Host-frozen Studio Build identity for opt-in Native runtime admission."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Mapping
+from typing import Any
+
+from pydantic import Field
+
+from .state import Contract
+
+
+def studio_mapping_digest(value: Mapping[str, Any]) -> str:
+    """Hash only JSON configuration; opaque objects cannot silently pass admission."""
+    encoded = json.dumps(
+        dict(value), ensure_ascii=False, sort_keys=True, separators=(",", ":"), allow_nan=False
+    ).encode("utf-8")
+    return "sha256:" + hashlib.sha256(encoded).hexdigest()
+
+
+class StudioAdmission(Contract):
+    build_id: str = Field(min_length=1)
+    manifest_sha256: str
+    model: str = Field(min_length=1)
+    project_dir: str = Field(min_length=1)
+    launch_config_digest: str = Field(pattern=r"^sha256:[0-9a-f]{64}$")
+    request_config_digest: str = Field(pattern=r"^sha256:[0-9a-f]{64}$")

ksadk/harness/native/subagents.py

@@ -0,0 +1,86 @@
+"""Host-issued delegation grants and child observations, never parent acceptance."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import Field, model_serializer, model_validator
+
+from .ports import ToolBudget
+from .state import Contract, RunScope
+
+
+class ChildRole(Contract):
+    role_id: str = Field(min_length=1, pattern=r"\S")
+    description: str
+    agent_id: str | None = Field(default=None, min_length=1)
+    tool_names: tuple[str, ...] = ()
+    workspace_access: Literal["read_only", "isolated_write"] = "read_only"
+    concurrent_safe: bool = False
+
+
+class ChildRunRequest(Contract):
+    scope: RunScope
+    parent_scope: RunScope
+    child_run_id: str
+    child_session_id: str
+    parent_run_id: str
+    parent_tool_call_id: str
+    parent_operation_key: str
+    task: str = Field(min_length=1, max_length=32000, pattern=r"\S")
+    # Immutable initial mode for an explicitly host-declared dual-mode tool.
+    # Promotion changes delivery through parent events, not this request.
+    delivery_mode: Literal["foreground", "background"] | None = Field(
+        default=None, exclude_if=lambda value: value is None
+    )
+    # A caller-declared delivery type, separate from the prose task and role
+    # capability grant. Absence retains the original request wire identity.
+    output_format: Literal["text", "json_object"] | None = None
+    # Select the host's current parent delivery shape. This does not inherit
+    # parent acceptance, tools, budget or any model-selected schema values.
+    output_contract: Literal["parent"] | None = None
+    # Host-bound source of a fresh turn in an already accounted child Session.
+    # It is not a request to reopen the source Run or replay its effects.
+    continuation_of: str | None = Field(default=None, min_length=1, max_length=256, pattern=r"\S")
+    continuation_parent_run_id: str | None = Field(
+        default=None, min_length=1, max_length=256, pattern=r"\S",
+    )
+    role: ChildRole
+    budget: ToolBudget
+
+    @model_serializer(mode="wrap")
+    def omit_unconfigured_output(self, serialize):
+        payload = serialize(self)
+        if self.output_format is None:
+            payload.pop("output_format", None)
+        if self.output_contract is None:
+            payload.pop("output_contract", None)
+        if self.continuation_of is None:
+            payload.pop("continuation_of", None)
+        if self.continuation_parent_run_id is None:
+            payload.pop("continuation_parent_run_id", None)
+        return payload
+
+    @model_validator(mode="after")
+    def explicit_parent_delivery(self):
+        if self.output_contract is not None and self.output_format != "json_object":
+            raise ValueError("parent output contract requires explicit object delivery")
+        if (self.continuation_of is None) != (self.continuation_parent_run_id is None):
+            raise ValueError("child continuation requires its source parent identity")
+        return self
+
+
+class ChildObservation(Contract):
+    schema_version: Literal["ksadk.child-observation/v1"] = "ksadk.child-observation/v1"
+    child_run_id: str
+    child_scope: RunScope
+    parent_run_id: str
+    parent_tool_call_id: str
+    phase: str
+    outcome: str | None = None
+    error_code: str | None = None
+    final_text: str = ""
+    text_truncated: bool = False
+    evidence_refs: tuple[str, ...] = ()
+    parent_acceptance: Literal["not_evaluated"] = "not_evaluated"
+    resource_usage_unknown: bool = False

ksadk/harness/native/task_policy.py

@@ -0,0 +1,99 @@
+"""Host-pinned task policies layered above generic tool and budget execution.
+
+Web observation rules are activated by an explicit configuration. The Kernel
+contains no implicit extension table or model-authored policy authority.
+"""
+
+from .ports import RunConfiguration, ToolResult, WorkspaceObservationPolicy
+from .state import RunSnapshot
+
+
+def invalidates_browser_observation(
+    result: ToolResult, policy: WorkspaceObservationPolicy | None
+) -> bool:
+    return bool(
+        policy
+        and any(
+            path.lower().endswith(policy.path_suffixes) for path in result.workspace_changed_paths
+        )
+    )
+
+
+def browser_observation_available(config: RunConfiguration) -> bool:
+    """Registered capabilities do not override the active goal's tool scope."""
+    allowed = config.contract.allowed_tool_names
+    return any(
+        tool.observation_role == "browser" and (allowed is None or tool.name in allowed)
+        for tool in config.tools
+    )
+
+
+def web_verification_only(snapshot: RunSnapshot, config: RunConfiguration) -> bool:
+    """Keep observation available after the last allowed late web mutation.
+
+    This gate is activated only for a Run that actually changed web files and
+    has a browser observation port. The preceding call can still repair; the
+    final tool-capable call cannot make its own browser evidence stale.
+    """
+    if config.workspace_observation_policy is None:
+        return False
+    reserve = config.limits.verification_reserve_model_calls
+    remaining = (
+        config.limits.max_model_calls - snapshot.model_budget_claimed
+    )
+    return bool(
+        reserve > 1
+        and config.limits.finalization_reserve_model_calls > 0
+        and snapshot.last_web_mutation_tool_call is not None
+        and browser_observation_available(config)
+        and 0 < remaining < reserve
+        and (
+            reserve < config.limits.finalization_reserve_model_calls + 4
+            or remaining <= config.limits.finalization_reserve_model_calls + 1
+        )
+        and remaining > config.limits.finalization_reserve_model_calls
+    )
+
+
+def web_observation_due(snapshot: RunSnapshot, config: RunConfiguration) -> bool:
+    """Require browser attempts before prolonged blind edits and near the limit.
+
+    A failed browser attempt counts as an attempt, not as successful evidence.
+    It unlocks the remaining repair window; later web edits can require a new
+    attempt. The final tool-capable turn still requires a fresh observation.
+    """
+    if config.workspace_observation_policy is None:
+        return False
+    limits = config.limits
+    reserve = limits.verification_reserve_model_calls
+    interval = limits.browser_observation_interval_tool_calls
+    remaining = limits.max_model_calls - snapshot.model_budget_claimed
+    last_mutation = snapshot.last_web_mutation_tool_call
+    if (
+        last_mutation is None
+        or remaining <= limits.finalization_reserve_model_calls
+        or not browser_observation_available(config)
+    ):
+        return False
+    observed = snapshot.last_browser_observation
+    unresolved = snapshot.unresolved_interaction_observation
+    last_attempt = max(
+        (
+            item
+            for item in (
+                snapshot.last_browser_attempt_tool_call,
+                *(
+                    entry["tool_call"]
+                    for entry in (observed, unresolved)
+                    if isinstance(entry, dict) and type(entry.get("tool_call")) is int
+                ),
+            )
+            if type(item) is int
+        ),
+        default=-1,
+    )
+    if last_attempt >= last_mutation:
+        return False
+    early_due = interval > 0 and snapshot.tool_calls - max(last_attempt, 0) >= interval
+    reserved_due = reserve >= limits.finalization_reserve_model_calls + 4 and remaining <= reserve
+    return early_due or reserved_due

ksadk/harness/native/task_progress.py

@@ -0,0 +1,86 @@
+"""Model-authored task planning kept separate from acceptance authority."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import Field, JsonValue, model_validator
+
+from .ports import ToolDefinition
+from .state import Contract
+
+TODO_WRITE_NAME = "TodoWrite"
+
+
+class TaskProgressItem(Contract):
+    # Optional for old clients. Explicit IDs survive editing/reordering; public
+    # projections derive deterministic content IDs for legacy items.
+    id: str | None = Field(default=None, min_length=1, max_length=180,
+                           exclude_if=lambda value: value is None)
+    content: str = Field(min_length=1, max_length=500, pattern=r"\S")
+    status: Literal["pending", "in_progress", "completed"]
+    priority: Literal["high", "medium", "low"]
+
+
+class TaskProgressUpdate(Contract):
+    todos: tuple[TaskProgressItem, ...] = Field(max_length=64)
+
+    @model_validator(mode="after")
+    def unique_content(self) -> TaskProgressUpdate:
+        normalized = [item.content.strip().casefold() for item in self.todos]
+        if len(set(normalized)) != len(normalized):
+            raise ValueError("task progress items must have unique content")
+        identities = [item.id for item in self.todos if item.id is not None]
+        if len(identities) != len(set(identities)):
+            raise ValueError("task progress items must have unique ids")
+        return self
+
+
+TODO_WRITE_DEFINITION = ToolDefinition(
+    name=TODO_WRITE_NAME,
+    context_role="task_planning",
+    description=(
+        "Replace the current session task list used to track multi-step work. "
+        "Send the complete list. Mark completed only after the work and required validation; "
+        "this planning status never substitutes for task acceptance."
+    ),
+    parameters={
+        "type": "object",
+        "additionalProperties": False,
+        "required": ["todos"],
+        "properties": {
+            "todos": {
+                "type": "array",
+                "maxItems": 64,
+                "items": {
+                    "type": "object",
+                    "additionalProperties": False,
+                    "required": ["content", "status", "priority"],
+                    "properties": {
+                        "id": {"type": "string", "minLength": 1, "maxLength": 180},
+                        "content": {"type": "string", "minLength": 1, "maxLength": 500},
+                        "status": {
+                            "type": "string",
+                            "enum": ["pending", "in_progress", "completed"],
+                        },
+                        "priority": {"type": "string", "enum": ["high", "medium", "low"]},
+                    },
+                },
+            }
+        },
+    },
+)
+
+
+def parse_task_progress(arguments: dict[str, JsonValue]) -> tuple[dict[str, JsonValue], ...]:
+    update = TaskProgressUpdate.model_validate(arguments)
+    return tuple(item.model_dump(mode="json") for item in update.todos)
+
+
+def summarize_task_progress(items: tuple[dict[str, JsonValue], ...]) -> dict[str, int]:
+    return {
+        "total": len(items),
+        "pending": sum(item["status"] == "pending" for item in items),
+        "in_progress": sum(item["status"] == "in_progress" for item in items),
+        "completed": sum(item["status"] == "completed" for item in items),
+    }

ksadk/harness/native/terminal_verification.py

@@ -0,0 +1,43 @@
+"""Qualify the final report against the current candidate and execution facts."""
+
+from .completion import CompletionCandidate, VerificationReport, _report_mismatch, reduce_completion
+from .ports import RunConfiguration
+from .state import RunSnapshot
+from .verification_binding import verification_subject_context_digest
+
+
+def prepare_terminal_verification(snapshot: RunSnapshot, config: RunConfiguration) -> RunSnapshot:
+    """Retire stale report pointers, preserving the original effect receipts.
+
+    A checkpoint or rejected final report can remain useful during the loop.
+    It cannot be published as the verdict for a different final candidate.
+    This happens in the authoritative terminal commit, never in the UI.
+    """
+    report = None
+    try:
+        candidate = CompletionCandidate.model_validate(snapshot.candidate)
+        observed = VerificationReport.model_validate(snapshot.verification)
+        if (
+            (snapshot.candidate or {}).get("purpose") != "checkpoint"
+            and candidate.final_text == snapshot.final_text
+            and snapshot.verification_tool_calls == snapshot.tool_calls
+            and candidate.subject_context_digest == verification_subject_context_digest(snapshot)
+            and _report_mismatch(config.contract, candidate, observed) is None
+        ):
+            report = observed
+    except (ValueError, TypeError):
+        # Old or rejected metadata is still available in its original receipt;
+        # absence of a qualified final report is not evidence of a passed check.
+        pass
+    updates = {
+        "verification": report.model_dump(mode="json") if report is not None else None,
+        "verification_tool_calls": snapshot.verification_tool_calls if report is not None else None,
+    }
+    if snapshot.outcome == "verified" and (
+        report is None
+        or reduce_completion(
+            config.contract, candidate, report, max_repairs=0,
+        ).outcome != "verified"
+    ):
+        updates.update(outcome="unverified", reason="terminal_verification_unavailable")
+    return snapshot.model_copy(update=updates)

ksadk/harness/native/tool_argument_feedback.py

@@ -0,0 +1,178 @@
+"""Bounded schema-derived diagnostics; they never normalize or admit a call."""
+
+from __future__ import annotations
+
+import json
+import re
+
+from jsonschema.exceptions import ValidationError
+from pydantic import JsonValue
+
+
+def _pointer(path) -> str:
+    return "/" + "/".join(
+        str(part).replace("~", "~0").replace("/", "~1") for part in path
+    )
+
+
+def _select_failure(error: ValidationError, validator):
+    """Narrow only an unambiguously tagged object union using declared consts."""
+    selected, relative_path = error, tuple(error.absolute_schema_path)
+    while selected.validator in {"oneOf", "anyOf"} and isinstance(selected.instance, dict):
+        branches = selected.validator_value
+        if not isinstance(branches, list):
+            break
+        matches = []
+        for index, branch in enumerate(branches):
+            properties = branch.get("properties", {}) if isinstance(branch, dict) else {}
+            if not isinstance(properties, dict):
+                continue
+            tags = {name: item["const"] for name, item in properties.items()
+                    if isinstance(item, dict) and "const" in item}
+            if tags and all(
+                name in selected.instance
+                and validator.evolve(schema={"const": value}).is_valid(selected.instance[name])
+                for name, value in tags.items()
+            ):
+                matches.append(index)
+        if len(matches) != 1:
+            break  # Unknown/ambiguous tags must not produce invented repair facts.
+        failures = [child for child in selected.context
+                    if child.schema_path and child.schema_path[0] == matches[0]]
+        if not failures:
+            break
+        selected = next(
+            (child for child in failures if child.validator == "type" and child.path),
+            failures[0],
+        )
+        # Retain the existing branch-relative diagnostic for action consumers.
+        # The original ValidationError parent chain retains the true origin.
+        relative_path = tuple(selected.schema_path)[1:]
+    return selected, relative_path
+
+
+def _physical_schema_path(schema: dict, selected: ValidationError) -> str | None:
+    value = schema
+    path = tuple(selected.absolute_schema_path)
+    try:
+        for part in path:
+            value = value[part]
+        # Local $ref validation may report a resolved rather than physical
+        # path. Only advertise an origin that actually exists in the definition.
+        if json.dumps(value, sort_keys=True) == json.dumps(
+            selected.validator_value, sort_keys=True
+        ):
+            pointer = _pointer(path)
+            return pointer if len(pointer) <= 2048 else None
+    except (KeyError, IndexError, TypeError):
+        pass
+    return None
+
+
+_JSON_TYPES = {"array", "boolean", "integer", "null", "number", "object", "string"}
+
+
+def _union_type_hint(error: ValidationError) -> list[str] | None:
+    """Describe only pure type alternatives, never enum values or other failures."""
+
+    def types(value):
+        values = [value] if isinstance(value, str) else value
+        if not isinstance(values, list) or not values or any(
+            not isinstance(item, str) or item not in _JSON_TYPES for item in values
+        ):
+            return None
+        return values
+
+    if error.validator != "anyOf" or not isinstance(error.validator_value, list):
+        return None
+    branches = error.validator_value
+    if not branches or len(error.context) != len(branches) or any(
+        child.validator != "type" or child.absolute_path != error.absolute_path
+        for child in error.context
+    ):
+        return None
+    result = []
+    for branch in branches:
+        if not isinstance(branch, dict) or set(branch) != {"type"}:
+            return None
+        allowed = types(branch["type"])
+        if allowed is None:
+            return None
+        result.extend(item for item in allowed if item not in result)
+    return result
+
+
+def _declared_names(schema_path) -> list[str]:
+    path, names, index = list(schema_path), [], 0
+    while index < len(path):
+        if path[index] == "properties" and index + 1 < len(path) and isinstance(
+            path[index + 1], str
+        ):
+            names.append(path[index + 1])
+            index += 2
+        else:
+            index += 1
+    return names
+
+
+def _declared_instance_path(selected: ValidationError) -> bool:
+    """Instance keys may be private map keys; repeat only host-declared names."""
+    keys = [part for part in selected.absolute_path if isinstance(part, str)]
+    return keys == _declared_names(selected.absolute_schema_path)
+
+
+def _schema_field(selected: ValidationError) -> str | None:
+    path = list(selected.absolute_schema_path)
+    if len(path) >= 3 and path[-3] == "properties" and isinstance(path[-2], str):
+        return path[-2]
+    return None
+
+
+def argument_error(error: ValidationError, schema: dict, validator) -> dict[str, JsonValue]:
+    selected, path = _select_failure(error, validator)
+    content: dict[str, JsonValue] = {
+        "code": "invalid_arguments",
+        "feedback_version": "schema-argument-feedback/v2",
+        "constraint": str(selected.validator),
+        "schema_path": _pointer(path)[:2048],
+        "instruction": "Correct arguments against this tool schema before retrying.",
+    }
+    if origin := _physical_schema_path(schema, selected):
+        content["source_schema_path"] = origin
+    declared = _declared_instance_path(selected)
+    instance_path = _pointer(selected.absolute_path) if selected.absolute_path else ""
+    if not declared:
+        content["instance_path_redacted"] = True
+    elif len(instance_path) <= 2048:
+        content["instance_path"] = instance_path
+    else:
+        content["instance_path_truncated"] = True
+    if selected.validator == "required" and isinstance(selected.instance, dict):
+        missing = [name for name in selected.validator_value if name not in selected.instance]
+        content["missing_fields"] = [name for name in missing[:20] if len(name) <= 256]
+        if len(missing) > 20 or any(len(name) > 256 for name in missing[:20]):
+            content["missing_fields_truncated"] = True
+    if (selected.validator == "additionalProperties" and selected.validator_value is False
+            and isinstance(selected.instance, dict)):
+        properties = selected.schema.get("properties", {})
+        patterns = selected.schema.get("patternProperties", {})
+        unexpected = [name for name in selected.instance if name not in properties
+                      and not any(re.search(pattern, name) for pattern in patterns)]
+        content["unexpected_fields"] = [name for name in unexpected[:20] if len(name) <= 256]
+        if len(unexpected) > 20 or any(len(name) > 256 for name in unexpected[:20]):
+            content["unexpected_fields_truncated"] = True
+    union_types = _union_type_hint(selected) if selected.path else None
+    if (selected.validator == "type" and selected.path) or union_types:
+        last = next(reversed(selected.path))
+        field = last if declared and isinstance(last, str) else _schema_field(selected)
+        if field is not None:
+            content["field"] = field[:80]
+        content["received_type"] = type(selected.instance).__name__
+        expected = selected.validator_value
+        if union_types:
+            content["expected_types"] = union_types[:8]
+        elif isinstance(expected, str):
+            content["expected_type"] = expected[:40]
+        elif isinstance(expected, list):
+            content["expected_types"] = expected[:8]
+    return content