agent-framework-lib 0.8.9__tar.gz → 0.8.9.post3__tar.gz

{agent_framework_lib-0.8.9/agent_framework_lib.egg-info → agent_framework_lib-0.8.9.post3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-framework-lib
-Version: 0.8.9
+Version: 0.8.9.post3
 Summary: A comprehensive Python framework for building and serving conversational AI agents with FastAPI
 Author-email: Sebastian Pavel <sebastian@cinco.ai>, Elliott Girard <elliott.girard@icloud.com>
 Maintainer-email: Sebastian Pavel <sebastian@cinco.ai>

{agent_framework_lib-0.8.9 → agent_framework_lib-0.8.9.post3}/agent_framework/core/model_clients.py

@@ -1243,6 +1243,7 @@ async def execute_chat_completion(
     stream: bool = False,
     max_tokens: int | None = None,
     temperature: float | None = None,
+    response_format: dict[str, Any] | None = None,
 ) -> "ChatExecutionResult | AsyncIterator[ChatExecutionChunk]":
     """Execute a chat completion against a raw provider client and normalize it.
 
@@ -1262,6 +1263,15 @@ async def execute_chat_completion(
         stream: When ``True``, returns an async iterator of ``ChatExecutionChunk``.
         max_tokens: Optional max output tokens (overrides ``model_params``).
         temperature: Optional sampling temperature (overrides ``model_params``).
+        response_format: Optional, provider-agnostic structured-output request in
+            the OpenAI shape — ``{"type": "json_object"}``,
+            ``{"type": "json_schema", "json_schema": {"name", "schema", ...}}`` or
+            ``{"type": "text"}``. Each provider helper translates it to that
+            provider's native mechanism (OpenAI: pass-through; Anthropic: a
+            system-prompt JSON directive since the Messages API has no
+            ``response_format``; Gemini: ``response_mime_type`` /
+            ``response_schema`` in ``generation_config``). ``None`` or
+            ``{"type": "text"}`` is a no-op.
 
     Returns:
         A ``ChatExecutionResult`` for non-streaming calls, or an
@@ -1280,6 +1290,7 @@ async def execute_chat_completion(
             stream=stream,
             max_tokens=max_tokens,
             temperature=temperature,
+            response_format=response_format,
         )
     if ANTHROPIC_AVAILABLE and isinstance(client, AsyncAnthropic):
         return await _execute_anthropic(
@@ -1289,6 +1300,7 @@ async def execute_chat_completion(
             stream=stream,
             max_tokens=max_tokens,
             temperature=temperature,
+            response_format=response_format,
         )
     if GEMINI_AVAILABLE and isinstance(client, genai.GenerativeModel):
         return await _execute_gemini(
@@ -1298,6 +1310,7 @@ async def execute_chat_completion(
             stream=stream,
             max_tokens=max_tokens,
             temperature=temperature,
+            response_format=response_format,
         )
     # Fallback: dispatch by duck-typing on the SDK surface when isinstance fails
     # (e.g., a subclass or a test double). This keeps dispatch robust without
@@ -1310,6 +1323,7 @@ async def execute_chat_completion(
             stream=stream,
             max_tokens=max_tokens,
             temperature=temperature,
+            response_format=response_format,
         )
     if hasattr(client, "messages") and hasattr(client.messages, "create"):
         return await _execute_anthropic(
@@ -1319,6 +1333,7 @@ async def execute_chat_completion(
             stream=stream,
             max_tokens=max_tokens,
             temperature=temperature,
+            response_format=response_format,
         )
     if hasattr(client, "generate_content_async"):
         return await _execute_gemini(
@@ -1328,6 +1343,7 @@ async def execute_chat_completion(
             stream=stream,
             max_tokens=max_tokens,
             temperature=temperature,
+            response_format=response_format,
         )
     raise TypeError(
         f"execute_chat_completion: unrecognized client type {type(client).__name__!r}; "
@@ -1335,6 +1351,93 @@ async def execute_chat_completion(
     )
 
 
+# ---------------------------------------------------------------------------
+# Provider-agnostic response_format translation (multi-provider support)
+# ---------------------------------------------------------------------------
+
+
+def _wants_json(response_format: dict[str, Any] | None) -> bool:
+    """Return ``True`` when ``response_format`` requests structured JSON output."""
+    if not response_format:
+        return False
+    return (response_format.get("type") or "").lower() in ("json_object", "json_schema")
+
+
+def _extract_json_schema(response_format: dict[str, Any] | None) -> dict[str, Any] | None:
+    """Extract the JSON schema dict from an OpenAI-shaped ``response_format``.
+
+    Supports ``{"type": "json_schema", "json_schema": {"schema": {...}}}`` and the
+    flatter ``{"type": "json_schema", "schema": {...}}``. Returns ``None`` when no
+    schema is present (e.g. plain ``{"type": "json_object"}``).
+    """
+    if not response_format:
+        return None
+    js = response_format.get("json_schema")
+    if isinstance(js, dict):
+        schema = js.get("schema")
+        if isinstance(schema, dict):
+            return schema
+        return js or None
+    schema = response_format.get("schema")
+    return schema if isinstance(schema, dict) else None
+
+
+def _openai_response_format(response_format: dict[str, Any] | None) -> dict[str, Any] | None:
+    """Normalize a provider-agnostic ``response_format`` to OpenAI's exact envelope.
+
+    OpenAI's Structured Outputs require ``{"type": "json_schema", "json_schema":
+    {"name": ..., "schema": ...}}``. We also accept the flatter
+    ``{"type": "json_schema", "schema": {...}}`` (used uniformly by the Anthropic/
+    Gemini helpers) and wrap it so the same ``response_format`` works across every
+    provider. ``json_object`` / ``text`` and an already-wrapped envelope pass
+    through unchanged.
+    """
+    if not response_format:
+        return response_format
+    if (response_format.get("type") or "").lower() != "json_schema":
+        return response_format
+    # Already in OpenAI's nested shape -> pass through.
+    if isinstance(response_format.get("json_schema"), dict):
+        return response_format
+    # Flat ``schema`` form -> wrap into the OpenAI envelope (a ``name`` is required
+    # by the API; default it when the caller did not supply one).
+    schema = response_format.get("schema")
+    if isinstance(schema, dict):
+        return {
+            "type": "json_schema",
+            "json_schema": {
+                "name": response_format.get("name", "response"),
+                "schema": schema,
+            },
+        }
+    return response_format
+
+
+def _ensure_openai_json_keyword(
+    messages: list[dict[str, Any]], response_format: dict[str, Any] | None
+) -> list[dict[str, Any]]:
+    """Guarantee the ``"json"`` keyword is present when OpenAI ``json_object`` is used.
+
+    OpenAI's JSON mode (``response_format={"type": "json_object"}``) returns a 400
+    (``'messages' must contain the word 'json'``) unless some message mentions
+    JSON. Structured Outputs (``json_schema``) has no such rule. When the keyword
+    is missing for a ``json_object`` request, append a trailing system instruction
+    (without mutating the caller's list).
+    """
+    if not response_format:
+        return messages
+    if (response_format.get("type") or "").lower() != "json_object":
+        return messages
+    for msg in messages:
+        content = msg.get("content")
+        text = content if isinstance(content, str) else (str(content) if content is not None else "")
+        if "json" in text.lower():
+            return messages
+    return list(messages) + [
+        {"role": "system", "content": "Respond with a single valid JSON object."}
+    ]
+
+
 async def _execute_openai(
     client: Any,
     model_params: dict[str, Any],
@@ -1343,25 +1446,36 @@ async def _execute_openai(
     stream: bool = False,
     max_tokens: int | None = None,
     temperature: float | None = None,
+    response_format: dict[str, Any] | None = None,
 ) -> "ChatExecutionResult | AsyncIterator[ChatExecutionChunk]":
     """Execute via ``client.chat.completions.create``.
 
     OpenAI accepts the system role INSIDE the messages list, so the messages are
     passed through unchanged (Req 2.11). Token usage is read from
     ``usage.prompt_tokens``/``usage.completion_tokens`` with reasoning tokens (if
-    reported) mapped to ``thinking_tokens``.
+    reported) mapped to ``thinking_tokens``. ``response_format`` is forwarded
+    natively (OpenAI supports ``json_object`` / ``json_schema``).
     """
     model, effective_temperature, effective_max_tokens = _resolve_call_params(
         model_params, max_tokens, temperature
     )
 
+    # Normalize response_format to OpenAI's exact envelope and ensure the "json"
+    # keyword exists for json_object mode (otherwise the API rejects the call).
+    normalized_rf = _openai_response_format(response_format)
+    effective_messages = _ensure_openai_json_keyword(messages, normalized_rf)
+
     create_kwargs: dict[str, Any] = {
         "model": model,
-        "messages": messages,
+        "messages": effective_messages,
         "temperature": effective_temperature,
     }
     if effective_max_tokens is not None:
         create_kwargs["max_tokens"] = effective_max_tokens
+    # OpenAI natively supports response_format; forward the normalized value (a
+    # plain ``{"type": "text"}`` is harmless, so only skip the no-op ``None``).
+    if normalized_rf is not None:
+        create_kwargs["response_format"] = normalized_rf
 
     if stream:
         # Ask OpenAI to include the usage chunk at the end of the stream so token
@@ -1441,6 +1555,40 @@ def _normalize_openai_usage(
     return input_tokens, output_tokens, 0, True
 
 
+def _anthropic_output_config(response_format: dict[str, Any] | None) -> dict[str, Any] | None:
+    """Translate a provider-agnostic ``response_format`` to Anthropic's native shape.
+
+    Anthropic's Messages API supports structured outputs via the ``output_config``
+    parameter: ``{"format": {"type": "json_schema", "schema": {...}}}``. The schema
+    is REQUIRED (there is no schema-less "json object" mode), so a plain
+    ``json_object`` request maps to a permissive object schema. Returns the
+    ``output_config`` dict when JSON is requested, else ``None``.
+
+    Structured outputs accept only a subset of JSON Schema (e.g. ``minimum`` /
+    ``maxLength`` / ``pattern`` are unsupported and would 400). We run the caller's
+    schema through the SDK's ``transform_schema`` — exactly what ``messages.parse``
+    does internally — which strips unsupported keywords (folding them into field
+    descriptions) and adds ``additionalProperties: false``. If the helper is
+    unavailable or fails, the raw schema is sent as-is.
+
+    With ``output_config`` the model emits the validated JSON as normal text, so
+    extraction and streaming use the standard text path (real incremental deltas).
+    """
+    if not _wants_json(response_format):
+        return None
+    schema = _extract_json_schema(response_format)
+    if not isinstance(schema, dict):
+        schema = {"type": "object"}
+    else:
+        try:  # Align the schema with Anthropic's supported JSON Schema subset.
+            from anthropic import transform_schema
+
+            schema = transform_schema(schema)
+        except Exception as exc:  # pragma: no cover - defensive: never block the call
+            logger.debug("[execute_chat_completion] anthropic transform_schema skipped: %s", exc)
+    return {"format": {"type": "json_schema", "schema": schema}}
+
+
 async def _execute_anthropic(
     client: Any,
     model_params: dict[str, Any],
@@ -1449,6 +1597,7 @@ async def _execute_anthropic(
     stream: bool = False,
     max_tokens: int | None = None,
     temperature: float | None = None,
+    response_format: dict[str, Any] | None = None,
 ) -> "ChatExecutionResult | AsyncIterator[ChatExecutionChunk]":
     """Execute via ``client.messages.create``.
 
@@ -1456,6 +1605,12 @@ async def _execute_anthropic(
     top-level ``system`` parameter, so the system-role message is lifted out of
     the messages list into ``system`` (Req 2.11). Token usage is read from
     ``usage.input_tokens``/``usage.output_tokens``.
+
+    The Anthropic Messages API supports structured outputs natively via the
+    ``output_config`` parameter (``{"format": {"type": "json_schema", "schema":
+    {...}}}``), so a JSON ``response_format`` is mapped to it and the model returns
+    validated JSON as normal text. Extraction and streaming therefore use the
+    standard text path — real incremental deltas, unlike a tool-use workaround.
     """
     model, effective_temperature, effective_max_tokens = _resolve_call_params(
         model_params, max_tokens, temperature
@@ -1466,6 +1621,9 @@ async def _execute_anthropic(
 
     system_text, non_system_messages = _split_system_messages(messages)
 
+    # Translate response_format → Anthropic's native structured-output config.
+    output_config = _anthropic_output_config(response_format)
+
     create_kwargs: dict[str, Any] = {
         "model": model,
         "messages": non_system_messages,
@@ -1474,6 +1632,8 @@ async def _execute_anthropic(
     }
     if system_text is not None:
         create_kwargs["system"] = system_text
+    if output_config is not None:
+        create_kwargs["output_config"] = output_config
 
     if stream:
 
@@ -1585,12 +1745,17 @@ async def _execute_gemini(
     stream: bool = False,
     max_tokens: int | None = None,
     temperature: float | None = None,
+    response_format: dict[str, Any] | None = None,
 ) -> "ChatExecutionResult | AsyncIterator[ChatExecutionChunk]":
     """Execute via Gemini ``GenerativeModel.generate_content_async``.
 
     Gemini keeps the system role inside the prompt / system instruction (Req 2.11).
     Token usage is read from ``usage_metadata`` (``prompt_token_count`` /
     ``candidates_token_count`` / ``thoughts_token_count``).
+
+    Gemini has no ``response_format`` parameter either: a JSON request is mapped to
+    ``generation_config.response_mime_type = "application/json"`` and, when a JSON
+    schema is supplied, ``generation_config.response_schema``.
     """
     model, effective_temperature, effective_max_tokens = _resolve_call_params(
         model_params, max_tokens, temperature
@@ -1600,6 +1765,11 @@ async def _execute_gemini(
     generation_config: dict[str, Any] = {"temperature": effective_temperature}
     if effective_max_tokens is not None:
         generation_config["max_output_tokens"] = effective_max_tokens
+    if _wants_json(response_format):
+        generation_config["response_mime_type"] = "application/json"
+        schema = _extract_json_schema(response_format)
+        if schema is not None:
+            generation_config["response_schema"] = schema
 
     if stream:
 

{agent_framework_lib-0.8.9 → agent_framework_lib-0.8.9.post3}/agent_framework/core/scratchpad_compressor.py

@@ -30,6 +30,18 @@ logger = logging.getLogger(__name__)
 
 TRUNCATION_MARKER = "\n\n[... contenu tronqué ...]\n\n"
 
+# Bandeau injecté en tête d'un tool_result tronqué de force parce qu'il dépassait
+# à lui seul le budget de contexte. Rend l'agent conscient que les données brutes
+# sont incomplètes et l'oriente vers des appels plus ciblés (pagination/morceaux).
+OVERSIZE_RESULT_NOTICE = (
+    "⚠️ RÉSULTAT TRONQUÉ AUTOMATIQUEMENT — l'appel outil a renvoyé un volume trop "
+    "grand pour la fenêtre de contexte. Les données brutes ci-dessous sont INCOMPLÈTES : "
+    "ne te fie pas aux valeurs partielles ni aux totaux/agrégats qui en dépendent. "
+    "Si tu as besoin des données complètes, refais des appels plus ciblés "
+    "(filtres précis, LIMIT/pagination, colonnes restreintes) pour traiter le résultat "
+    "par morceaux.\n---\n"
+)
+
 # OpenAI enforces a 10 485 760 character limit per message content.
 # We use a conservative 8M limit to leave headroom for JSON serialization
 # overhead, tool_call metadata, and other wrapper text added by the SDK.
@@ -163,7 +175,12 @@ class ScratchpadCompressor:
 
         return "\n".join(parts)
 
-    def _truncate_single_result(self, message: ChatMessage, target_tokens: int) -> ChatMessage:
+    def _truncate_single_result(
+        self,
+        message: ChatMessage,
+        target_tokens: int,
+        oversize_notice: bool = False,
+    ) -> ChatMessage:
         """Tronque le contenu d'un tool_result en gardant début + marqueur + fin.
 
         Aplatit d'abord tous les blocks en texte brut pour que la troncature
@@ -176,6 +193,10 @@ class ScratchpadCompressor:
         Args:
             message: Message tool_result à tronquer.
             target_tokens: Nombre cible de tokens pour le message tronqué.
+            oversize_notice: Si True et qu'une troncature a réellement lieu,
+                préfixe le contenu avec OVERSIZE_RESULT_NOTICE pour avertir
+                l'agent que les données brutes sont incomplètes. Les tokens du
+                bandeau sont réservés dans la cible pour ne pas la dépasser.
 
         Returns:
             Nouveau ChatMessage avec le contenu tronqué (blocks nettoyés).
@@ -195,7 +216,14 @@ class ScratchpadCompressor:
             k: v for k, v in (message.additional_kwargs or {}).items() if k not in ("tool_calls",)
         }
 
-        if current_tokens <= target_tokens or target_tokens <= 0:
+        # Réserver les tokens du bandeau d'avertissement dans la cible pour que
+        # (bandeau + contenu tronqué) reste sous target_tokens.
+        notice = OVERSIZE_RESULT_NOTICE if oversize_notice else ""
+        notice_tokens = self._token_counter.count_tokens(notice).count if notice else 0
+        effective_target = max(0, target_tokens - notice_tokens)
+
+        if current_tokens <= effective_target or target_tokens <= 0:
+            # Aucune troncature nécessaire → pas de bandeau (rien n'est perdu).
             if content != (message.content or ""):
                 return ChatMessage(
                     role=message.role,
@@ -206,7 +234,7 @@ class ScratchpadCompressor:
 
         # Réserver des tokens pour le marqueur de troncature
         marker_tokens = self._token_counter.count_tokens(TRUNCATION_MARKER).count
-        available_tokens = max(0, target_tokens - marker_tokens)
+        available_tokens = max(0, effective_target - marker_tokens)
 
         # Répartir entre début et fin (60% début, 40% fin)
         begin_tokens = int(available_tokens * 0.6)
@@ -219,17 +247,18 @@ class ScratchpadCompressor:
         end_chars = max(0, int(end_tokens * chars_per_token))
 
         if begin_chars + end_chars >= len(content):
-            if content != (message.content or ""):
+            final_content = notice + content if notice else content
+            if final_content != (message.content or ""):
                 return ChatMessage(
                     role=message.role,
-                    content=content,
+                    content=final_content,
                     additional_kwargs=clean_kwargs,
                 )
             return message
 
         begin_part = content[:begin_chars]
         end_part = content[-end_chars:] if end_chars > 0 else ""
-        truncated_content = begin_part + TRUNCATION_MARKER + end_part
+        truncated_content = notice + begin_part + TRUNCATION_MARKER + end_part
 
         return ChatMessage(
             role=message.role,
@@ -324,8 +353,11 @@ class ScratchpadCompressor:
         if not old_entries:
             last_pair_tokens = self._count_tokens(last_pair)
             if last_pair_tokens > available_for_scratchpad:
-                # Tronquer le tool_result de la dernière paire
-                compressed_pair = self._truncate_last_pair(last_pair, available_for_scratchpad)
+                # Tronquer le tool_result de la dernière paire + avertir l'agent
+                # (le résultat unique dépasse à lui seul le budget).
+                compressed_pair = self._truncate_last_pair(
+                    last_pair, available_for_scratchpad, oversize_notice=True
+                )
                 tokens_after = self._count_tokens(compressed_pair)
                 self._log_compression(
                     entries_before,
@@ -343,6 +375,17 @@ class ScratchpadCompressor:
 
         # Cas 2 : il y a des anciennes entrées à compresser
         last_pair_tokens = self._count_tokens(last_pair)
+
+        # Garde-fou : si la dernière paire dépasse à elle seule le budget, la
+        # préserver verbatim est impossible (sinon résumer les anciennes entrées
+        # ne sert à rien — c'est le bug du blob unique géant). On la tronque
+        # aussi, avec bandeau d'avertissement pour l'agent.
+        if last_pair_tokens > available_for_scratchpad:
+            last_pair = self._truncate_last_pair(
+                last_pair, available_for_scratchpad, oversize_notice=True
+            )
+            last_pair_tokens = self._count_tokens(last_pair)
+
         target_old_tokens = max(0, available_for_scratchpad - last_pair_tokens)
 
         # Tenter le résumé LLM
@@ -443,6 +486,7 @@ class ScratchpadCompressor:
         self,
         last_pair: list[ChatMessage],
         available_tokens: int,
+        oversize_notice: bool = False,
     ) -> list[ChatMessage]:
         """Tronque le tool_result dans la dernière paire pour respecter le budget.
 
@@ -452,6 +496,8 @@ class ScratchpadCompressor:
         Args:
             last_pair: Dernière paire de messages (tool_call + tool_result).
             available_tokens: Tokens disponibles pour toute la paire.
+            oversize_notice: Propagé à _truncate_single_result pour préfixer le
+                bandeau d'avertissement quand le tool_result est tronqué.
 
         Returns:
             Paire avec le tool_result tronqué si nécessaire.
@@ -462,7 +508,9 @@ class ScratchpadCompressor:
         for msg in last_pair:
             if msg.role == MessageRole.TOOL:
                 remaining = max(0, available_tokens - tokens_used)
-                result.append(self._truncate_single_result(msg, remaining))
+                result.append(
+                    self._truncate_single_result(msg, remaining, oversize_notice=oversize_notice)
+                )
             else:
                 tokens_used += self._count_tokens([msg])
                 result.append(msg)

{agent_framework_lib-0.8.9 → agent_framework_lib-0.8.9.post3}/agent_framework/security/authz.py

@@ -86,26 +86,44 @@ def resolve_effective_user_id(current_user: str, requested_user_id: str | None)
     return current_user
 
 
-def is_owner(resource_user_id: str | None, principal: str) -> bool:
-    """Vérifie que ``principal`` possède la ressource.
+def is_owner(
+    resource_user_id: str | None,
+    principal: str,
+    *,
+    is_admin: bool = False,
+) -> bool:
+    """Vérifie que ``principal`` possède la ressource (autorisation role-based).
+
+    Le ``principal`` passé DOIT être l'**utilisateur effectif** de la requête
+    (résolu via :func:`resolve_effective_user_id`), pas le pseudo-principal d'une
+    clé API partagée par un portail. L'accès cross-utilisateur n'est accordé que
+    via le **rôle admin** (``is_admin=True``), pas par la confiance accordée à
+    tout détenteur de clé.
+
+    Note (changement de modèle) : le court-circuit historique
+    ``trust_client_user_id() -> True`` est **supprimé**. ``AUTH_TRUST_CLIENT_USER_ID``
+    ne sert plus qu'à *résoudre* l'utilisateur effectif (honorer le ``user_id``
+    fourni par un portail de confiance) dans :func:`resolve_effective_user_id` ;
+    il n'autorise plus, à lui seul, l'accès aux ressources d'autrui.
 
     Args:
         resource_user_id: Identifiant du propriétaire de la ressource
             (``None`` si la ressource n'a pas de propriétaire connu).
-        principal: Identité authentifiée demandant l'accès.
+        principal: Identité **effective** demandant l'accès.
+        is_admin: ``True`` si l'appelant est authentifié comme admin (rôle
+            privilégié QA/support) — court-circuite la vérification de propriété.
 
     Returns:
-        ``True`` si le principal possède la ressource, si le mode développement
-        est actif et que le principal est ``"anonymous"`` (compat mono-utilisateur),
-        ou si le client est de confiance (``AUTH_TRUST_CLIENT_USER_ID`` — le portail
-        de confiance peut accéder aux ressources de n'importe quel end-user).
+        ``True`` si l'appelant est admin, si ``principal`` possède la ressource,
+        ou si le mode développement est actif et que ``principal`` est
+        ``"anonymous"`` (compat mono-utilisateur). ``False`` sinon.
     """
+    if is_admin:
+        return True
     if resource_user_id is not None and resource_user_id == principal:
         return True
     if dev_mode_enabled() and principal == ANONYMOUS_PRINCIPAL:
         return True
-    if trust_client_user_id():
-        return True
     return False
 
 

{agent_framework_lib-0.8.9 → agent_framework_lib-0.8.9.post3}/agent_framework/utils/post_install.py

@@ -1076,6 +1076,70 @@ def _find_local_wheel() -> Path | None:
     return None
 
 
+_IMAGE_PIN_NAME = "sandbox-image-pin"
+
+
+def _ensure_image_pin(tag: str) -> None:
+    """Keep a tiny container running off the CURRENT sandbox image so an external
+    ``docker image prune`` / ``docker system prune`` cannot remove it.
+
+    A running container's image — AND its tag — survive a prune. The pin is
+    (re)created whenever it is missing OR points at a different image id, because
+    ``docker build -t <tag>`` moves the tag to a NEW image and leaves a stale pin
+    on the old one (then the new, unpinned, tagged image gets pruned → the tag
+    vanishes → ``ImagePullFailed`` on the next sandbox). Re-pinning the freshly
+    built/current image right here closes that window on every boot and rebuild.
+    Best-effort: never fatal, never blocks the agent.
+    """
+    if not _docker_ok():
+        return
+    try:
+        tag_inspect = subprocess.run(
+            ["docker", "image", "inspect", "-f", "{{.Id}}", tag],
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        if tag_inspect.returncode != 0:
+            return  # tag not present locally — nothing to pin
+        want = (tag_inspect.stdout or "").strip()
+        pin = subprocess.run(
+            ["docker", "inspect", "-f", "{{.State.Running}} {{.Image}}", _IMAGE_PIN_NAME],
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+        if pin.returncode == 0:
+            running, _, img = (pin.stdout or "").strip().partition(" ")
+            if running == "true" and img == want:
+                return  # already pinned to the current image — nothing to do
+        subprocess.run(["docker", "rm", "-f", _IMAGE_PIN_NAME], capture_output=True, timeout=30)
+        r = subprocess.run(
+            [
+                "docker",
+                "run",
+                "-d",
+                "--name",
+                _IMAGE_PIN_NAME,
+                "--restart",
+                "always",
+                "--entrypoint",
+                "sleep",
+                tag,
+                "infinity",
+            ],
+            capture_output=True,
+            text=True,
+            timeout=60,
+        )
+        if r.returncode == 0:
+            logger.info("[sandbox] pinned image %s (prune-proof) via %s", tag, _IMAGE_PIN_NAME)
+        else:
+            logger.warning("[sandbox] image pin failed: %s", (r.stderr or "")[-200:])
+    except Exception as exc:  # noqa: BLE001 — pinning must never break startup
+        logger.warning("[sandbox] image pin error: %s", exc)
+
+
 def _render_sandbox_dockerfile(install_line: str, version: str = "") -> str:
     """Self-contained Dockerfile for the per-session sandbox image.
 
@@ -1131,6 +1195,7 @@ def ensure_sandbox_image(tag: str = _SANDBOX_IMAGE_TAG) -> tuple[bool, str | Non
     if _sandbox_image_exists(tag) and not force:
         built_version = _sandbox_image_version(tag)
         if built_version == _afl_version:
+            _ensure_image_pin(tag)  # keep it prune-proof even when no rebuild is needed
             return True, None
         logger.info(
             "[sandbox] image %s built for version %r != package %r — rebuilding",
@@ -1173,6 +1238,7 @@ def ensure_sandbox_image(tag: str = _SANDBOX_IMAGE_TAG) -> tuple[bool, str | Non
     finally:
         shutil.rmtree(build_dir, ignore_errors=True)
     if r.returncode == 0:
+        _ensure_image_pin(tag)  # pin the freshly built image so a prune can't drop the tag
         return True, None
     return False, f"sandbox image build failed: {r.stderr[-400:]}"