maf-sandbox 0.1.0__tar.gz

maf_sandbox-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SOKOLAI BV
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

maf_sandbox-0.1.0/PKG-INFO

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: maf-sandbox
+Version: 0.1.0
+Summary: One seam between an application and any sandbox provider, for Microsoft Agent Framework — reference implementation of agent-framework#7568: backend protocol, selection, and the rule that a weaker isolation boundary is never used in a deployed environment.
+Keywords: agent-framework,microsoft-agent-framework,sandbox,isolation,ai-agents
+Author: SOKOLAI BV
+Author-email: SOKOLAI BV <info@sokolai.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Typing :: Typed
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: agent-framework-core>=1.13.0,<2
+Requires-Python: >=3.12, <3.15
+Project-URL: Homepage, https://www.sokol.ai
+Project-URL: Source, https://github.com/sokolaidev/maf-extensions
+Project-URL: Issues, https://github.com/sokolaidev/maf-extensions/issues
+Description-Content-Type: text/markdown
+
+# maf-sandbox
+
+> **Experimental.** This package is early-stage (`0.1.0`, `Development Status :: 4 - Beta`) — its API may change or be removed in a future release without notice. Importing it emits a one-time `MafSandboxExperimentalWarning`; suppress it with `warnings.filterwarnings("ignore", category=maf_sandbox.MafSandboxExperimentalWarning)` once you've read the notice.
+
+This package is not affiliated with, endorsed by, or a product of Microsoft — it is a third-party reference implementation of [microsoft/agent-framework#7568](https://github.com/microsoft/agent-framework/issues/7568), written for use with [Microsoft Agent Framework](https://aka.ms/AgentFramework) but with no dependency on it in its protocol layer.
+
+## Quickstart
+
+```bash
+pip install maf-sandbox
+```
+
+```python
+from maf_sandbox import Isolation, SandboxKey, SandboxRouter, SandboxSpec, WorkspaceContext
+
+# Implement SandboxBackend against your own provider — or install maf-sandbox-aca for a
+# ready-made Azure Container Apps Sandboxes backend — then wire it into a router:
+router = SandboxRouter([my_backend], deployed=False)
+sandbox = await router.acquire(SandboxKey(scope="tenant-1", thread_id="t-1", agent_dir="devops"), SandboxSpec(kind="bicep", image="bicep-sandbox:0.46.1", egress_allow=("mcr.microsoft.com",), work_dir="/workspace"))
+```
+
+## Threat model
+
+This package draws no isolation boundary itself — it is protocol and policy over whatever a `SandboxBackend` implementation actually provides. `Isolation` states three tiers a backend can declare, from strongest to weakest: `vm` (a VM boundary — the whole guest, not just a process, is untrusted), `container` (a shared-kernel boundary), and `process` (no boundary beyond the OS's own process isolation). `SandboxRouter` enforces the one rule below on top of that declaration; the package's job is to make an unsafe backend selection fail loudly at construction, not silently at first use. Beyond backend selection, this layer has nothing else to get wrong: it holds no credentials, executes nothing, and reaches no network — everything security-relevant about a *specific* sandbox lives in the backend that implements it.
+
+## The vocabulary
+
+| | |
+|---|---|
+| `SandboxKey` | `(scope, thread_id, agent_dir)` — the one sandbox a caller may reach |
+| `SandboxSpec` | what a sandbox of a given *kind* needs: image, egress allowlist, work dir |
+| `Sandbox` | `write_file` + `exec` — all a workload gets |
+| `SandboxBackend` | `acquire` / `dispose` / `dispose_scope` |
+| `SandboxRouter` | picks the backend, enforces the deployed rule |
+| `SandboxPurger` | duck-typed `purge_scoped_thread(scope, thread_id)` for a host's delete path |
+
+`SandboxKey`'s scope and thread come from the host's request context through `WorkspaceContext`, whose fields are **callables read at call time** rather than values. That is deliberate: a key a caller can supply is a key a *model* can supply, and that would let one conversation address another's sandbox.
+
+`SandboxSpec.egress_allow` is an allowlist — everything not named is denied, so an empty tuple means no network. Stating it positively means a spec that forgets to mention egress gets the closed configuration rather than the open one.
+
+## The one rule that is not a convenience
+
+```python
+DEPLOYED_ISOLATION = frozenset({Isolation.VM})
+```
+
+A backend declares its own `isolation` (`vm` / `container` / `process`). When the host reports it is running **deployed**, the router refuses to select anything weaker than a VM boundary — raising `SandboxBackendNotPermitted` at construction, not at first use, so a misconfigured deployment cannot start with the feature apparently enabled and quietly unsafe.
+
+It refuses rather than degrades. Falling back to a stronger backend would hide a misconfiguration; proceeding with the weaker one would break claims the host's security posture makes about every execution surface. Neither is better than an error.
+
+A hardened container runtime (gVisor, Kata, Firecracker) is deliberately *not* in the permitted set. Admitting one is a decision for whoever owns those posture claims, taken there first.
+
+## Writing a backend
+
+Implement `name`, `isolation`, `acquire`, `dispose`, `dispose_scope`. Two things worth knowing before you start:
+
+**`acquire` is get-or-create.** A workload's fix-round loop calls it every iteration; returning a cold sandbox each time turns a seconds-long loop into a minutes-long one.
+
+**`dispose_scope` must not consult only your process's memory.** A multi-replica host serves a conversation delete wherever it lands, so the replica that created the sandbox is usually not the one deleting it. Derive the set from the service — labels, a listing, whatever your provider offers. A backend that skips this leaves billable compute running and the bug is invisible on a single-replica dev box.
+
+Both `dispose` methods are best-effort by contract: purge must never fail a delete.
+
+## Provenance
+
+Extracted from a production agent application, where this seam was written for its first execution surface: a tool that compiles agent-authored infrastructure code in a sandbox. The deployed-isolation rule above is not a preference — it is what a security review concluded when it worked through what a shared-kernel boundary does *not* close for code an agent wrote.
+
+---
+
+Maintained by [SOKOLAI BV](https://www.sokol.ai).

maf_sandbox-0.1.0/README.md

@@ -0,0 +1,69 @@
+# maf-sandbox
+
+> **Experimental.** This package is early-stage (`0.1.0`, `Development Status :: 4 - Beta`) — its API may change or be removed in a future release without notice. Importing it emits a one-time `MafSandboxExperimentalWarning`; suppress it with `warnings.filterwarnings("ignore", category=maf_sandbox.MafSandboxExperimentalWarning)` once you've read the notice.
+
+This package is not affiliated with, endorsed by, or a product of Microsoft — it is a third-party reference implementation of [microsoft/agent-framework#7568](https://github.com/microsoft/agent-framework/issues/7568), written for use with [Microsoft Agent Framework](https://aka.ms/AgentFramework) but with no dependency on it in its protocol layer.
+
+## Quickstart
+
+```bash
+pip install maf-sandbox
+```
+
+```python
+from maf_sandbox import Isolation, SandboxKey, SandboxRouter, SandboxSpec, WorkspaceContext
+
+# Implement SandboxBackend against your own provider — or install maf-sandbox-aca for a
+# ready-made Azure Container Apps Sandboxes backend — then wire it into a router:
+router = SandboxRouter([my_backend], deployed=False)
+sandbox = await router.acquire(SandboxKey(scope="tenant-1", thread_id="t-1", agent_dir="devops"), SandboxSpec(kind="bicep", image="bicep-sandbox:0.46.1", egress_allow=("mcr.microsoft.com",), work_dir="/workspace"))
+```
+
+## Threat model
+
+This package draws no isolation boundary itself — it is protocol and policy over whatever a `SandboxBackend` implementation actually provides. `Isolation` states three tiers a backend can declare, from strongest to weakest: `vm` (a VM boundary — the whole guest, not just a process, is untrusted), `container` (a shared-kernel boundary), and `process` (no boundary beyond the OS's own process isolation). `SandboxRouter` enforces the one rule below on top of that declaration; the package's job is to make an unsafe backend selection fail loudly at construction, not silently at first use. Beyond backend selection, this layer has nothing else to get wrong: it holds no credentials, executes nothing, and reaches no network — everything security-relevant about a *specific* sandbox lives in the backend that implements it.
+
+## The vocabulary
+
+| | |
+|---|---|
+| `SandboxKey` | `(scope, thread_id, agent_dir)` — the one sandbox a caller may reach |
+| `SandboxSpec` | what a sandbox of a given *kind* needs: image, egress allowlist, work dir |
+| `Sandbox` | `write_file` + `exec` — all a workload gets |
+| `SandboxBackend` | `acquire` / `dispose` / `dispose_scope` |
+| `SandboxRouter` | picks the backend, enforces the deployed rule |
+| `SandboxPurger` | duck-typed `purge_scoped_thread(scope, thread_id)` for a host's delete path |
+
+`SandboxKey`'s scope and thread come from the host's request context through `WorkspaceContext`, whose fields are **callables read at call time** rather than values. That is deliberate: a key a caller can supply is a key a *model* can supply, and that would let one conversation address another's sandbox.
+
+`SandboxSpec.egress_allow` is an allowlist — everything not named is denied, so an empty tuple means no network. Stating it positively means a spec that forgets to mention egress gets the closed configuration rather than the open one.
+
+## The one rule that is not a convenience
+
+```python
+DEPLOYED_ISOLATION = frozenset({Isolation.VM})
+```
+
+A backend declares its own `isolation` (`vm` / `container` / `process`). When the host reports it is running **deployed**, the router refuses to select anything weaker than a VM boundary — raising `SandboxBackendNotPermitted` at construction, not at first use, so a misconfigured deployment cannot start with the feature apparently enabled and quietly unsafe.
+
+It refuses rather than degrades. Falling back to a stronger backend would hide a misconfiguration; proceeding with the weaker one would break claims the host's security posture makes about every execution surface. Neither is better than an error.
+
+A hardened container runtime (gVisor, Kata, Firecracker) is deliberately *not* in the permitted set. Admitting one is a decision for whoever owns those posture claims, taken there first.
+
+## Writing a backend
+
+Implement `name`, `isolation`, `acquire`, `dispose`, `dispose_scope`. Two things worth knowing before you start:
+
+**`acquire` is get-or-create.** A workload's fix-round loop calls it every iteration; returning a cold sandbox each time turns a seconds-long loop into a minutes-long one.
+
+**`dispose_scope` must not consult only your process's memory.** A multi-replica host serves a conversation delete wherever it lands, so the replica that created the sandbox is usually not the one deleting it. Derive the set from the service — labels, a listing, whatever your provider offers. A backend that skips this leaves billable compute running and the bug is invisible on a single-replica dev box.
+
+Both `dispose` methods are best-effort by contract: purge must never fail a delete.
+
+## Provenance
+
+Extracted from a production agent application, where this seam was written for its first execution surface: a tool that compiles agent-authored infrastructure code in a sandbox. The deployed-isolation rule above is not a preference — it is what a security review concluded when it worked through what a shared-kernel boundary does *not* close for code an agent wrote.
+
+---
+
+Maintained by [SOKOLAI BV](https://www.sokol.ai).

maf_sandbox-0.1.0/pyproject.toml

@@ -0,0 +1,71 @@
+[project]
+name = "maf-sandbox"
+version = "0.1.0"
+description = "One seam between an application and any sandbox provider, for Microsoft Agent Framework — reference implementation of agent-framework#7568: backend protocol, selection, and the rule that a weaker isolation boundary is never used in a deployed environment."
+readme = "README.md"
+requires-python = ">=3.12,<3.15"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "agent-framework",
+    "microsoft-agent-framework",
+    "sandbox",
+    "isolation",
+    "ai-agents",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Typing :: Typed",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = ["agent-framework-core>=1.13.0,<2"]
+
+[[project.authors]]
+name = "SOKOLAI BV"
+email = "info@sokolai.com"
+
+[project.urls]
+Homepage = "https://www.sokol.ai"
+Source = "https://github.com/sokolaidev/maf-extensions"
+Issues = "https://github.com/sokolaidev/maf-extensions/issues"
+
+[tool.uv.build-backend]
+module-name = "maf_sandbox"
+module-root = "src"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+extend-select = [
+    "I",
+    "UP",
+    "D100",
+    "D101",
+    "D103",
+    "D104",
+]
+ignore = ["UP037"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = [
+    "D101",
+    "D103",
+]
+
+[tool.pyright]
+include = ["src"]
+typeCheckingMode = "strict"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["uv_build>=0.11.24,<0.12.0"]
+build-backend = "uv_build"

maf_sandbox-0.1.0/pyproject.toml.orig

@@ -0,0 +1,87 @@
+[project]
+name = "maf-sandbox"
+version = "0.1.0"
+description = "One seam between an application and any sandbox provider, for Microsoft Agent Framework — reference implementation of agent-framework#7568: backend protocol, selection, and the rule that a weaker isolation boundary is never used in a deployed environment."
+readme = "README.md"
+requires-python = ">=3.12,<3.15"
+authors = [{ name = "SOKOLAI BV", email = "info@sokolai.com" }]
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "agent-framework",
+    "microsoft-agent-framework",
+    "sandbox",
+    "isolation",
+    "ai-agents",
+]
+# No `License ::` classifier: PEP 639 deprecated them in favour of the `license`
+# expression above, and carrying both is the combination build tools are allowed to reject.
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Typing :: Typed",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+# The protocol modules (`_protocol`, `_router`, `_purger`) stay import-clean of everything
+# but the standard library — giving THEM a backend dependency, or a MAF one, would make this
+# layer the thing it exists to keep apart. `TestZeroDependencies` and `TestOnlyDeclaredDependencies`
+# (tests/test_sandbox_router.py) pin that at the source-scan level, which is a stronger and
+# more honest guarantee than a dependency list, since a stray import would still resolve
+# fine in this workspace with every other member already on the path.
+#
+# The dist-level dependency below exists for a different module: `maf_sandbox.maf`, the
+# MAF-glue module this package's dist ships alongside the protocol. Only that module may
+# import `agent_framework`; the boundary test's zero-dependency claim narrows to name the
+# protocol modules explicitly rather than the whole distribution once that module lands.
+dependencies = [
+    "agent-framework-core>=1.13.0,<2",
+]
+
+[project.urls]
+Homepage = "https://www.sokol.ai"
+Source = "https://github.com/sokolaidev/maf-extensions"
+Issues = "https://github.com/sokolaidev/maf-extensions/issues"
+
+# No [tool.uv.sources] here, deliberately: this repository resolves agent-framework-core
+# from PyPI at the released range declared above — the same artifact every consumer of the
+# published wheel gets. (The host application these packages were extracted from pins MAF
+# from git `main` on its own side; that pin stayed there when the packages moved here.)
+
+[tool.uv.build-backend]
+module-name = "maf_sandbox"
+module-root = "src"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+extend-select = ["I", "UP", "D100", "D101", "D103", "D104"]
+ignore = ["UP037"]
+
+[tool.ruff.lint.per-file-ignores]
+# ruff resolves [tool.ruff] per file by the NEAREST ancestor pyproject.toml that has one —
+# once this package gained its own [tool.ruff] section, the host application's root
+# pyproject.toml per-file-ignore entry for this package's tests stopped reaching these
+# files, so this package carries its own copy.
+"tests/**" = ["D101", "D103"]
+
+# Self-contained type checking, scoped to this package — strict, unlike the host
+# application's root config, which runs its own type checker in basic mode: this is new,
+# purpose-built code with no legacy baseline to carry. `tests/` is out for the same reason
+# the root config leaves tests out everywhere else in that repo: fixtures and hand-rolled
+# fakes are not where a strict checker's objections are signal.
+[tool.pyright]
+include = ["src"]
+typeCheckingMode = "strict"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["uv_build>=0.11.24,<0.12.0"]
+build-backend = "uv_build"

maf_sandbox-0.1.0/src/maf_sandbox/__init__.py

@@ -0,0 +1,105 @@
+"""Sandbox router: one seam between a host application and any sandbox provider.
+
+```
+app  ->  SandboxRouter  ->  backend  ->  the sandbox
+```
+
+A workload asks for a sandbox and runs a command in it.  A backend decides what actually
+boots — an ACA Sandbox (`maf-sandbox-aca`) today, a local Docker container or an
+in-process fake later.  Neither knows about the other, which is what lets the same tool run
+against all of them unchanged.
+
+The router exists for two things a backend cannot own:
+
+- **Which backend serves a request.** Configuration, not an import, decides.
+- **The deployed-isolation rule.** A backend weaker than a VM boundary is refused outright
+  when the host reports it is running deployed — see
+  :class:`~maf_sandbox._router.SandboxBackendNotPermitted`.  This is the router's one part
+  that is a security property rather than a convenience, so it is enforced at construction
+  and pinned by tests.
+
+This package imports no backend and no host application.
+
+One module sits deliberately outside that claim and is deliberately not re-exported here:
+:mod:`maf_sandbox.maf`, the MAF glue (``make_workspace_context``, ``sandboxed_tool``, and the
+purge participant).  It is the only module allowed to import ``agent_framework``, and keeping
+it off this ``__init__`` is what lets ``import maf_sandbox`` stay cheap and framework-free for
+a backend or a test that only speaks the protocol.  Reach it by name —
+``from maf_sandbox.maf import sandboxed_tool``.
+"""
+
+from __future__ import annotations
+
+from ._error_detail import error_detail
+from ._protocol import (
+    ExecResult,
+    Isolation,
+    Sandbox,
+    SandboxBackend,
+    SandboxKey,
+    SandboxSpec,
+    WorkspaceContext,
+)
+from ._purger import SandboxPurger
+from ._router import (
+    DEPLOYED_ISOLATION,
+    NoSandboxBackend,
+    SandboxBackendNotPermitted,
+    SandboxRouter,
+)
+
+__all__ = [
+    "DEPLOYED_ISOLATION",
+    "ExecResult",
+    "Isolation",
+    "MafSandboxExperimentalWarning",
+    "NoSandboxBackend",
+    "Sandbox",
+    "SandboxBackend",
+    "SandboxBackendNotPermitted",
+    "SandboxKey",
+    "SandboxPurger",
+    "SandboxRouter",
+    "SandboxSpec",
+    "WorkspaceContext",
+    "error_detail",
+]
+
+# --- Experimental-package notice ---------------------------------------------------------
+# This package is early-stage (0.1.0, "Development Status :: 4 - Beta"). Mirrors
+# `agent_framework`'s own experimental-feature idiom (see its `_feature_stage` module and
+# `ExperimentalWarning`, a `FutureWarning` subclass) but deliberately subclasses
+# `UserWarning` instead: a host that runs under `python -W error` (many CI/production
+# launchers do) would have importing this package alone raise before any of its own code
+# runs if the category were a `FutureWarning`. `UserWarning` keeps the notice
+# informational-by-default while staying a real, catchable, filterwarnings-suppressible
+# category — see the try/except immediately below for how `-W error` is handled anyway.
+#
+# Duplicated (not imported from a shared module) in each of the three maf-sandbox*
+# packages on purpose — a shared warnings module would be a cross-package dependency this
+# split is designed to avoid.
+import warnings as _warnings
+
+
+class MafSandboxExperimentalWarning(UserWarning):
+    """Warning category for maf-sandbox's experimental-package notice."""
+
+
+def _warn_experimental() -> None:
+    message = (
+        "maf_sandbox is experimental and may change or be removed in future versions "
+        "without notice."
+    )
+    try:
+        _warnings.warn(message, category=MafSandboxExperimentalWarning, stacklevel=2)
+    except MafSandboxExperimentalWarning:
+        # A host running under `python -W error` (or with a blanket
+        # `filterwarnings("error")` active) turns the warning above into an exception at
+        # the call site. Importing a package must never fail because of an informational
+        # notice, so it is swallowed here — this is the one piece of state a `-W error`
+        # host is allowed to change: whether the notice was printed, never whether the
+        # import succeeded.
+        pass
+
+
+_warn_experimental()

maf_sandbox-0.1.0/src/maf_sandbox/_error_detail.py

@@ -0,0 +1,48 @@
+"""``error_detail``: as much of a provider failure as a log can usefully carry.
+
+``str()`` on an azure-core ``HttpResponseError`` is just
+``Operation returned an invalid status 'Bad Request'`` — the *reason* is in the response
+body, which that string drops.  A 400 that says only "Bad Request" cannot be acted on: it
+took a hand-written probe against the live service to discover that one such failure meant
+the app's identity had no role on the sandbox group.
+
+This started life inside the bicep kind, the only caller that needed it.  The ACA backend's
+own warning logs have the identical gap — a bare ``%s`` of the exception, dropping the same
+response body — so it moved here where every backend and every kind can reach it, rather than
+being copied.
+
+Duck-typed on purpose, and stdlib-only: it reads ``status_code`` and ``response.text()`` off
+whatever it is given, which is how it works against azure-core's ``HttpResponseError`` — or
+any other SDK's exception shaped the same way — without importing it.  This is a log-only
+utility; the caller decides separately what a model or end user is told, and that message
+must stay sanitized regardless of what this function returns.
+"""
+
+from __future__ import annotations
+
+__all__ = ["error_detail"]
+
+
+def error_detail(exc: Exception) -> str:
+    """As much of a failure as the log can usefully carry.
+
+    ``str()`` on an azure-core ``HttpResponseError`` is just
+    ``Operation returned an invalid status 'Bad Request'`` — the *reason* is in the response
+    body, which that string drops.  A 400 that says only "Bad Request" cannot be acted on:
+    it took a hand-written probe against the live service to discover that one such failure
+    meant the app's identity had no role on the sandbox group.  This is log-only; the model
+    still sees the sanitized message.
+    """
+    parts = [f"{type(exc).__name__}: {exc}"]
+    status = getattr(exc, "status_code", None)
+    if status is not None:
+        parts.append(f"status={status}")
+    response = getattr(exc, "response", None)
+    if response is not None:
+        try:
+            body = response.text()
+        except Exception:  # noqa: BLE001 - diagnostics must not raise
+            body = None
+        if body:
+            parts.append(f"body={body[:600]}")
+    return " | ".join(parts)