agentinputlab 0.1.0a1__py3-none-any.whl

workers/official_arenas/protocol.py

@@ -0,0 +1,334 @@
+"""Shared, dependency-light contracts for official arena providers."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import os
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Protocol, runtime_checkable
+
+REPLAY_INVENTORY_PROTOCOL = "agentinputlab.official-arena-replay-inventory.v1"
+EXECUTABLE_PAYLOAD_PROTOCOL = "agentinputlab.executable-release-payload.v1"
+_SHA256 = re.compile(r"^[0-9a-f]{64}$")
+SHARED_BUDGET_PATH_ENV = "AILAB_SHARED_BUDGET_OVERRIDE_PATH"
+SHARED_BUDGET_SHA256_ENV = "AILAB_SHARED_BUDGET_OVERRIDE_SHA256"
+_BUDGET_FIELDS = frozenset(
+    {
+        "profile_id",
+        "max_model_calls",
+        "max_retrieval_calls",
+        "max_tool_calls",
+        "max_output_tokens",
+        "max_context_tokens",
+        "max_output_tokens_per_call",
+    }
+)
+_STANDARD_SHARED_BUDGET = {
+    "max_model_calls": 8,
+    "max_retrieval_calls": 8,
+    "max_tool_calls": 8,
+    "max_output_tokens": 4096,
+    # ExecutionBudget.max_context_tokens is a cumulative input-token budget,
+    # not the per-request model context window.  Eight calls may each carry a
+    # growing interactive history, so the frozen run-level cap is eight times
+    # the 32,768-token per-call context control.
+    "max_context_tokens": 262144,
+    "max_output_tokens_per_call": 512,
+}
+
+
+class OfficialArenaError(RuntimeError):
+    """Stable fail-closed error raised by an official runtime provider."""
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderArmResult:
+    """One completed official episode plus scorer and usage evidence."""
+
+    metrics: Mapping[str, float]
+    trace: Mapping[str, Any]
+    usage: Mapping[str, int | float] = field(default_factory=dict)
+    runtime_instance_id: str = ""
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.metrics, Mapping) or not self.metrics:
+            raise OfficialArenaError("official provider metrics must be non-empty")
+        for name, value in self.metrics.items():
+            if (
+                not isinstance(name, str)
+                or not name.strip()
+                or isinstance(value, bool)
+                or not isinstance(value, (int, float))
+                or not math.isfinite(float(value))
+            ):
+                raise OfficialArenaError("official provider metrics are invalid")
+        if not isinstance(self.trace, Mapping) or not self.trace:
+            raise OfficialArenaError("official provider trace must be non-empty")
+        if not isinstance(self.usage, Mapping):
+            raise OfficialArenaError("official provider usage must be an object")
+        if not isinstance(self.runtime_instance_id, str) or len(self.runtime_instance_id) != 64:
+            raise OfficialArenaError(
+                "official provider runtime_instance_id must be a SHA-256 digest"
+            )
+
+
+@runtime_checkable
+class OfficialArenaProvider(Protocol):
+    """Runtime-specific capture and continuation boundary."""
+
+    benchmark_id: str
+    source_revision: str
+    scorer_id: str
+    scorer_revision: str
+
+    def doctor(self, config: Mapping[str, Any]) -> tuple[str, ...]: ...
+
+    def capture(
+        self,
+        config: Mapping[str, Any],
+        *,
+        output_root: Path,
+    ) -> tuple[Mapping[str, Any], ...]: ...
+
+    def run_arm(
+        self,
+        config: Mapping[str, Any],
+        *,
+        replay_record: Mapping[str, Any],
+        arm_payload: Mapping[str, Any],
+        seed: int,
+        role: str,
+        work_dir: Path,
+    ) -> ProviderArmResult: ...
+
+
+def canonical_json(value: Any) -> str:
+    return json.dumps(
+        value,
+        ensure_ascii=False,
+        sort_keys=True,
+        separators=(",", ":"),
+        allow_nan=False,
+    )
+
+
+def content_hash(value: Any) -> str:
+    return hashlib.sha256(canonical_json(value).encode("utf-8")).hexdigest()
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for block in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(block)
+    return digest.hexdigest()
+
+
+def validate_shared_budget(value: Any) -> Mapping[str, int | str]:
+    """Validate one paper-wide resource budget shared by every arena arm."""
+
+    if not isinstance(value, Mapping) or set(value) != _BUDGET_FIELDS:
+        raise OfficialArenaError("shared budget override fields are invalid")
+    if not isinstance(value["profile_id"], str) or not value["profile_id"].strip():
+        raise OfficialArenaError("shared budget profile_id must be non-empty")
+    for name in _BUDGET_FIELDS - {"profile_id"}:
+        raw = value[name]
+        if isinstance(raw, bool) or not isinstance(raw, int) or raw < 1:
+            raise OfficialArenaError(f"shared budget {name} must be a positive integer")
+    if value["max_output_tokens_per_call"] > value["max_output_tokens"]:
+        raise OfficialArenaError(
+            "shared budget per-call output cap exceeds the cumulative output cap"
+        )
+    return value
+
+
+def standard_shared_budget(multiplier: float = 1.0) -> dict[str, int | str]:
+    """Materialize the frozen paper control profile at one resource multiplier."""
+
+    if (
+        isinstance(multiplier, bool)
+        or not isinstance(multiplier, (int, float))
+        or not math.isfinite(float(multiplier))
+        or multiplier <= 0
+    ):
+        raise OfficialArenaError("shared budget multiplier must be finite and positive")
+    return {
+        "profile_id": f"paper-shared-budget-x{multiplier:g}",
+        **{
+            name: max(1, round(value * multiplier))
+            for name, value in _STANDARD_SHARED_BUDGET.items()
+        },
+    }
+
+
+def resolve_shared_budget_config(config: Mapping[str, Any]) -> Mapping[str, Any]:
+    """Attach an authenticated process-level budget factor to a provider config.
+
+    The factor is read by every official provider before capture.  Consequently
+    the exact same budget becomes part of the captured visible state, the
+    intervention input hash, and the fair-comparison dependency locks.
+    """
+
+    raw_path = os.environ.get(SHARED_BUDGET_PATH_ENV)
+    raw_sha256 = os.environ.get(SHARED_BUDGET_SHA256_ENV)
+    if not raw_path and not raw_sha256:
+        return config
+    if not raw_path or not raw_sha256 or _SHA256.fullmatch(raw_sha256) is None:
+        raise OfficialArenaError("shared budget environment binding is incomplete")
+    unresolved = Path(raw_path).expanduser()
+    path = unresolved.resolve()
+    if unresolved.is_symlink() or not path.is_file() or sha256_file(path) != raw_sha256:
+        raise OfficialArenaError("shared budget environment artifact differs")
+    try:
+        loaded = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        raise OfficialArenaError("shared budget artifact is invalid JSON") from exc
+    override = validate_shared_budget(loaded)
+    existing = config.get("budget_override")
+    if existing is not None and existing != override:
+        raise OfficialArenaError("explicit and environment budget overrides differ")
+    return {**config, "budget_override": dict(override)}
+
+
+def visible_shared_budget(config: Mapping[str, Any], fallback: Mapping[str, Any]) -> dict[str, Any]:
+    """Return the exact budget exposed to intervention code at capture time."""
+
+    raw = config.get("budget_override")
+    if raw is None:
+        return dict(fallback)
+    override = validate_shared_budget(raw)
+    return {
+        "max_model_calls": override["max_model_calls"],
+        "max_retrieval_calls": override["max_retrieval_calls"],
+        "max_tool_calls": override["max_tool_calls"],
+        "max_output_tokens": override["max_output_tokens"],
+        "max_context_tokens": override["max_context_tokens"],
+        "max_cost_usd": None,
+    }
+
+
+def require_materialized_budget(
+    state: Mapping[str, Any],
+    config: Mapping[str, Any],
+) -> Mapping[str, Any]:
+    """Fail closed if a materialized arm changed the shared resource budget."""
+
+    raw = config.get("budget_override")
+    budget = state.get("budget")
+    if not isinstance(budget, Mapping):
+        raise OfficialArenaError("materialized state has no execution budget")
+    if raw is None:
+        return budget
+    expected = visible_shared_budget(config, {})
+    if dict(budget) != expected:
+        raise OfficialArenaError("materialized arm changed the shared budget factor")
+    return budget
+
+
+def validate_dependency_hashes(
+    value: Any,
+    *,
+    label: str,
+) -> Mapping[str, str]:
+    if (
+        not isinstance(value, Mapping)
+        or not value
+        or any(
+            not isinstance(name, str)
+            or not name
+            or not isinstance(digest, str)
+            or _SHA256.fullmatch(digest) is None
+            for name, digest in value.items()
+        )
+    ):
+        raise OfficialArenaError(f"{label} dependency locks are invalid")
+    return value
+
+
+def materialized_state(arm_payload: Mapping[str, Any]) -> Mapping[str, Any]:
+    if (
+        not isinstance(arm_payload, Mapping)
+        or arm_payload.get("schema_version") != 1
+        or arm_payload.get("protocol") != EXECUTABLE_PAYLOAD_PROTOCOL
+    ):
+        raise OfficialArenaError(
+            "official arena requires an executable materialized release payload"
+        )
+    execution = arm_payload.get("intervention_execution")
+    if not isinstance(execution, Mapping):
+        raise OfficialArenaError("intervention_execution is missing")
+    state = execution.get("materialized_state")
+    if not isinstance(state, Mapping):
+        raise OfficialArenaError("materialized intervention state is missing")
+    if content_hash(state) != execution.get("output_state_hash"):
+        raise OfficialArenaError("materialized intervention state hash differs")
+    if execution.get("input_state_hash") != arm_payload.get("visible_state_hash"):
+        raise OfficialArenaError("intervention input state differs from the checkpoint")
+    return state
+
+
+def intervention_usage(arm_payload: Mapping[str, Any]) -> Mapping[str, int | float]:
+    execution = arm_payload.get("intervention_execution")
+    if not isinstance(execution, Mapping) or not isinstance(execution.get("usage"), Mapping):
+        raise OfficialArenaError("intervention usage is missing")
+    return execution["usage"]
+
+
+def merge_usage(*values: Mapping[str, Any]) -> dict[str, int | float]:
+    integer_fields = (
+        "model_calls",
+        "retrieval_calls",
+        "tool_calls",
+        "embedding_calls",
+        "unpriced_model_calls",
+        "input_tokens",
+        "output_tokens",
+    )
+    float_fields = (
+        "cpu_seconds",
+        "accelerator_seconds",
+        "cost_usd",
+        "compute_cost_usd",
+    )
+    result: dict[str, int | float] = {name: 0 for name in integer_fields}
+    result.update({name: 0.0 for name in float_fields})
+    for value in values:
+        if not isinstance(value, Mapping):
+            raise OfficialArenaError("usage contribution must be an object")
+        for name in integer_fields:
+            raw = value.get(name, 0)
+            if isinstance(raw, bool) or not isinstance(raw, int) or raw < 0:
+                raise OfficialArenaError(f"usage field {name} must be non-negative integer")
+            result[name] += raw
+        for name in float_fields:
+            raw = value.get(name, 0.0)
+            if (
+                isinstance(raw, bool)
+                or not isinstance(raw, (int, float))
+                or not math.isfinite(float(raw))
+                or raw < 0
+            ):
+                raise OfficialArenaError(f"usage field {name} must be non-negative finite")
+            result[name] += float(raw)
+    return result
+
+
+__all__ = [
+    "EXECUTABLE_PAYLOAD_PROTOCOL",
+    "REPLAY_INVENTORY_PROTOCOL",
+    "OfficialArenaError",
+    "OfficialArenaProvider",
+    "ProviderArmResult",
+    "canonical_json",
+    "content_hash",
+    "intervention_usage",
+    "materialized_state",
+    "merge_usage",
+    "sha256_file",
+    "validate_dependency_hashes",
+]

workers/official_arenas/providers/__init__.py

@@ -0,0 +1 @@
+"""Official arena provider implementations."""

workers/official_arenas/providers/_live_history.py

@@ -0,0 +1,228 @@
+"""Optional native-message history view; no native state/tool object is rewritten."""
+from __future__ import annotations
+
+import copy
+import json
+from collections.abc import Mapping
+from pathlib import Path
+
+from ..protocol import OfficialArenaError
+
+
+def validate_history_transform(hook):
+    if hook is not None and not all(callable(getattr(hook, name, None))
+                                    for name in ("transform", "fingerprint")):
+        raise OfficialArenaError("native history requires transform and fingerprint methods")
+
+
+class NativeHistorySession:
+    """Separate helper usage from target usage, enforcing their shared caps."""
+
+    def __init__(self, hook, materialized, budget):
+        validate_history_transform(hook)
+        self.hook = hook
+        self.materialized = copy.deepcopy(dict(materialized))
+        self.budget = dict(budget)
+        self.usage = {}
+
+    def remaining(self, agent_usage):
+        fields = {"max_model_calls": "model_calls", "max_output_tokens": "output_tokens"}
+        return {cap: int(self.budget[cap]) - int(agent_usage.get(name, 0))
+                - int(self.usage.get(name, 0)) for cap, name in fields.items()}
+
+    def messages(self, native, *, encode, agent_usage):
+        """Map only system/first-user text; reuse retained native objects exactly."""
+        from agentinputlab.integrations.live_history import _balanced_tool_frames
+
+        raw = encode(native)
+        logical = self._transform(raw, agent_usage=agent_usage)
+        first_user = next((i for i, row in enumerate(raw) if row.get("role") == "user"), None)
+        if (first_user is None or first_user == 0 or raw[0].get("role") != "system"
+                or len(logical) <= first_user or logical[0].get("role") != "system"
+                or logical[first_user].get("role") != "user"):
+            raise OfficialArenaError("native history changed the system/first-user framing")
+        if list(logical[1:first_user]) != raw[1:first_user]:
+            raise OfficialArenaError("native history changed a pre-user native frame")
+        text_slots = {0, first_user}
+        result, cursor = [], 0
+        for i, row in enumerate(logical):
+            row = dict(row)
+            if i in text_slots:
+                original = raw[i]
+                if ({k: v for k, v in row.items() if k != "content"}
+                        != {k: v for k, v in original.items() if k != "content"}
+                        or not isinstance(row.get("content"), str)):
+                    raise OfficialArenaError("native history changed non-text first-turn fields")
+                result.append(native[i].model_copy(update={"content": row["content"]}, deep=True))
+                cursor = i + 1
+            else:
+                index = next((j for j in range(cursor, len(raw)) if raw[j] == row), None)
+                if index is None:
+                    raise OfficialArenaError("native history invented or reordered a retained frame")
+                result.append(copy.deepcopy(native[index]))
+                cursor = index + 1
+        if encode(result) != list(logical):
+            raise OfficialArenaError("native history message roundtrip changed wire fields")
+        if not _balanced_tool_frames(logical):
+            raise OfficialArenaError("native history orphaned tool frames")
+        return result
+
+    def _transform(self, raw, *, agent_usage):
+        """Shared measured helper budget; protocol-specific roundtrips stay separate."""
+        from agentinputlab.observability import external_usage_counters, normalize_external_usage
+
+        remaining = self.remaining(agent_usage)
+        answer = self.hook.transform(copy.deepcopy(raw), state=copy.deepcopy(self.materialized),
+                                     remaining_budget=remaining)
+        if not isinstance(answer, Mapping) or set(answer) != {"messages", "usage"}:
+            raise OfficialArenaError("native history response fields differ")
+        usage = answer["usage"]
+        if not isinstance(usage, Mapping) or not {"model_calls", "output_tokens"} <= usage.keys():
+            raise OfficialArenaError("native history requires actual call/output usage")
+        if usage["model_calls"] and not {"input_tokens", "retrieval_calls"} <= usage.keys():
+            raise OfficialArenaError("native history calls require complete actual usage")
+        usage = external_usage_counters(normalize_external_usage({
+            "model_calls": 0, "retrieval_calls": 0, "input_tokens": 0, "output_tokens": 0, **usage}))
+        for key, value in usage.items():
+            self.usage[key] = self.usage.get(key, 0) + value
+        if not usage["model_calls"] and (usage["input_tokens"] or usage["output_tokens"]):
+            raise OfficialArenaError("skipped native history cannot report model tokens")
+        if usage["tool_calls"] or usage["retrieval_calls"] or usage["embedding_calls"]:
+            raise OfficialArenaError("native history cannot execute tools or retrieval")
+        if usage["model_calls"] >= remaining["max_model_calls"] or usage["output_tokens"] >= remaining["max_output_tokens"]:
+            raise OfficialArenaError("native history failed to reserve downstream budget")
+        logical = answer["messages"]
+        if not isinstance(logical, (list, tuple)) or any(not isinstance(row, Mapping) for row in logical):
+            raise OfficialArenaError("native history messages are invalid")
+        return list(logical)
+
+    def combined_usage(self, target_usage):
+        result = dict(target_usage)
+        for key, value in self.usage.items():
+            result[key] = result.get(key, 0) + value
+        return result
+
+    def write_receipt(self, path: Path, *, target_usage):
+        value = dict(fingerprint=self.hook.fingerprint(), records=list(getattr(self.hook, "records", ())),
+                     history_usage=dict(self.usage), target_usage=dict(target_usage),
+                     agent_and_history_usage=self.combined_usage(target_usage),
+                     original_shared_budget=self.budget,
+                     native_environment_history_NOT_modified=True)
+        if hasattr(self, "responses_records"):
+            value["responses_view"] = dict(protocol="native.responses.user_boundary.v1",
+                                           records=list(self.responses_records))
+        if path.exists():
+            if json.loads(path.read_text(encoding="utf-8")) != value:
+                raise OfficialArenaError("native history receipt changed before finalization")
+            return
+        with path.open("x", encoding="utf-8") as handle:
+            json.dump(value, handle, sort_keys=True, indent=2, allow_nan=False)
+
+
+class ResponsesHistorySession(NativeHistorySession):
+    """A reversible optimizer view, never a Chat-Completions wire conversion.
+
+    Real instructions and injected system items are immutable. Each complete
+    assistant/tool episode between actual user messages is one atomic text view
+    for ACON. Retained Items are deep-copied from the original native objects,
+    including reasoning, annotations, call IDs, arguments and tool results.
+    Invoke only at new user turns, not inside a function-call continuation.
+    """
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.responses_records = []
+
+    def responses(self, native, *, instructions, agent_usage):
+        from agentinputlab.contracts.serialization import canonical_json, content_hash
+
+        if not isinstance(instructions, str) or not instructions:
+            raise OfficialArenaError("Responses history requires real text instructions")
+        if not isinstance(native, (list, tuple)):
+            raise OfficialArenaError("Responses history requires native input Items")
+        rows = []
+        for item in native:
+            row = dict(item) if isinstance(item, Mapping) else item.model_dump(mode="json")
+            if not isinstance(row, dict):
+                raise OfficialArenaError("Responses history Item is not serializable")
+            rows.append(row)
+        system_indices = [i for i, row in enumerate(rows) if row.get("role") in {"system", "developer"}]
+        policy = canonical_json(dict(instructions=instructions,
+                                     input_policy_items=[rows[i] for i in system_indices]))
+        raw = [dict(role="system", content=policy)]
+        groups = []
+        pending_group = []
+
+        def flush():
+            if not pending_group:
+                return
+            pending, seen = set(), set()
+            for i in pending_group:
+                row = rows[i]
+                if row.get("type") == "function_call":
+                    call = row.get("call_id")
+                    if not isinstance(call, str) or not call or call in seen:
+                        raise OfficialArenaError("Responses history has duplicate or missing call_id")
+                    pending.add(call)
+                    seen.add(call)
+                elif row.get("type") == "function_call_output":
+                    call = row.get("call_id")
+                    if call not in pending:
+                        raise OfficialArenaError("Responses history has an orphaned function result")
+                    pending.remove(call)
+            if pending:
+                raise OfficialArenaError("Responses history has an incomplete function episode")
+            raw.append(dict(role="assistant", content=canonical_json([rows[i] for i in pending_group])))
+            groups.append(list(pending_group))
+            pending_group.clear()
+
+        for i, row in enumerate(rows):
+            if i in system_indices:
+                continue  # Preserved on the native wire and included in the policy view.
+            if row.get("role") == "user":
+                flush()
+                content = row.get("content")
+                if isinstance(content, list) and len(content) == 1 and isinstance(content[0], Mapping):
+                    if content[0].get("type") != "input_text":
+                        raise OfficialArenaError("Responses history user Item is not plain text")
+                    content = content[0].get("text")
+                if not isinstance(content, str):
+                    raise OfficialArenaError("Responses history user Item is not plain text")
+                raw.append(dict(role="user", content=content))
+                groups.append([i])
+            else:
+                pending_group.append(i)
+        flush()
+        if len(raw) < 2 or raw[1]["role"] != "user" or raw[-1]["role"] != "user":
+            raise OfficialArenaError("Responses history requires an actual new user-turn boundary")
+        logical = self._transform(raw, agent_usage=agent_usage)
+        if (len(logical) < 2 or logical[0] != raw[0]
+                or set(logical[1]) != {"role", "content"}
+                or logical[1].get("role") != "user" or not isinstance(logical[1].get("content"), str)):
+            raise OfficialArenaError("Responses history changed immutable policy or first-user framing")
+        selected = set(system_indices + groups[0])
+        cursor = 2
+        for row in logical[2:]:
+            index = next((j for j in range(cursor, len(raw)) if raw[j] == row), None)
+            if index is None:
+                raise OfficialArenaError("Responses history invented or reordered native Items")
+            selected.update(groups[index - 1])
+            cursor = index + 1
+        # The current real user request must remain; no model-generated turn is inserted.
+        if not set(groups[-1]) <= selected:
+            raise OfficialArenaError("Responses history removed the current user turn")
+        result = [copy.deepcopy(item) for i, item in enumerate(native) if i in selected]
+        first_index = groups[0][0]
+        first_output = sorted(selected).index(first_index)
+        original = rows[first_index]
+        content = logical[1]["content"]
+        if isinstance(original["content"], list):
+            content = [{**original["content"][0], "text": content}]
+        if isinstance(result[first_output], Mapping):
+            result[first_output] = {**result[first_output], "content": content}
+        else:
+            result[first_output] = result[first_output].model_copy(update={"content": content}, deep=True)
+        self.responses_records.append(dict(native_input_hash=content_hash(rows),
+            optimizer_view_hash=content_hash(raw), retained_source_item_indices=sorted(selected),
+            policy_unchanged=True, native_items_NOT_chat_messages=True))
+        return result, instructions

workers/official_arenas/providers/_message_compat.py

@@ -0,0 +1,77 @@
+"""Narrow message-shape compatibility helpers for self-hosted model templates."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+
+def requires_qwen38_initial_system_message(model: Any) -> bool:
+    """Return whether the served alias uses Qwen3.8's strict system placement."""
+
+    if not isinstance(model, str):
+        return False
+    alias = model.strip().casefold().replace("_", "-")
+    return alias == "qwen3.8" or alias.startswith("qwen3.8-")
+
+
+def normalize_qwen38_reasoning_effort(model: Any, effort: Any) -> Any:
+    """Map STATE-Bench's strongest effort label to Qwen3.8's equivalent."""
+
+    if requires_qwen38_initial_system_message(model) and effort == "high":
+        return "xhigh"
+    return effort
+
+
+def coalesce_chat_system_messages(messages: Sequence[Any]) -> list[Any]:
+    """Move chat system content into one leading message without reordering peers."""
+
+    copied = [dict(item) if isinstance(item, Mapping) else item for item in messages]
+    system_items: list[dict[str, Any]] = []
+    non_system_items: list[Any] = []
+    for item in copied:
+        if isinstance(item, Mapping) and item.get("role") == "system":
+            content = item.get("content")
+            if not isinstance(content, str):
+                raise TypeError("Qwen3.8 system message content must be text")
+            system_items.append(dict(item))
+        else:
+            non_system_items.append(item)
+    if not system_items:
+        return copied
+    merged = dict(system_items[0])
+    merged["content"] = "\n\n".join(item["content"] for item in system_items)
+    return [merged, *non_system_items]
+
+
+def fold_responses_system_messages_into_instructions(
+    input_items: Sequence[Any],
+    instructions: Any,
+) -> tuple[list[Any], Any]:
+    """Fold Responses input system items into its single instructions field.
+
+    Qwen3.8's chat template accepts only the leading system slot.  The Responses
+    transport renders ``instructions`` there, so later system-role input items
+    must be removed and appended to that field in their original order.
+    """
+
+    copied = [dict(item) if isinstance(item, Mapping) else item for item in input_items]
+    system_contents: list[str] = []
+    non_system_items: list[Any] = []
+    for item in copied:
+        if isinstance(item, Mapping) and item.get("role") == "system":
+            content = item.get("content")
+            if not isinstance(content, str):
+                raise TypeError("Qwen3.8 Responses system item content must be text")
+            system_contents.append(content)
+        else:
+            non_system_items.append(item)
+    if not system_contents:
+        return copied, instructions
+    if instructions is not None and not isinstance(instructions, str):
+        raise TypeError("Qwen3.8 Responses instructions must be text or None")
+    parts = []
+    if instructions:
+        parts.append(instructions)
+    parts.extend(system_contents)
+    return non_system_items, "\n\n".join(parts)