@matt82198/aesop 0.3.2 → 0.4.1

package/driver/context_pack.py

@@ -0,0 +1,454 @@
+#!/usr/bin/env python3
+"""Context pack builder for the OrchestratorDriver seam.
+
+Enforces cardinal rule 4 in code: the orchestrator reads ONLY control files
+from the file brain, never arbitrary paths. build_context_pack() constructs
+size-bounded, deterministic snapshots from allowlisted sources with a manifest
+of what was included/truncated.
+
+Context sources are logical names, NOT paths:
+  'state' -> STATE.md (from repo/conductor root)
+  'buildlog_tail' -> last N lines of BUILDLOG.md
+  'tracker_open' -> subset of open items from state/tracker.json
+  'brief:<explicit-path>' -> explicitly passed file under repo/conductor allowlist
+
+Attempts to read arbitrary paths raise ContextPackViolation (the code-level
+enforcement of cardinal rule 4).
+
+Packs are size-bounded (default ~32KB) with deterministic truncation
+(oldest-first for logs).
+
+stdlib-only, ASCII-only, Windows + Linux safe.
+"""
+
+import json
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+
+class ContextPackViolation(Exception):
+    """Raised when a context pack request violates the allowlist."""
+    pass
+
+
+@dataclass
+class ContextPack:
+    """Snapshot of orchestrator-readable control files, size-bounded.
+
+    Attributes:
+        decision_type: Decision class name (e.g., 'rank_backlog', 'adjudicate_findings').
+        sources_requested: Logical names passed to build_context_pack().
+        content: Dict mapping source -> (text content | error message).
+        evidence: Dict mapping evidence_name -> text (code excerpts, repro output, etc.).
+        manifest: List of {source, included, truncated, truncation_reason, size_bytes}.
+        evidence_manifest: List of {name, included, truncated, truncation_reason, size_bytes}.
+        total_size_bytes: Sum of all content sizes.
+        total_size_cap: The size limit enforced (default ~32KB).
+        evidence_size_bytes: Sum of all evidence sizes.
+        evidence_size_cap: Separate size limit for evidence (default ~4KB).
+    """
+
+    decision_type: str
+    sources_requested: Tuple[str, ...] = field(default_factory=tuple)
+    content: Dict[str, str] = field(default_factory=dict)
+    evidence: Dict[str, str] = field(default_factory=dict)
+    manifest: List[Dict] = field(default_factory=list)
+    evidence_manifest: List[Dict] = field(default_factory=list)
+    total_size_bytes: int = 0
+    total_size_cap: int = 32768  # ~32KB default
+    evidence_size_bytes: int = 0
+    evidence_size_cap: int = 4096  # ~4KB default for evidence
+
+
+def _is_allowed_path(path: str, repo_root: str, conductor_root: str) -> bool:
+    """Check if a path is in the allowlist (repo or conductor root only).
+
+    Args:
+        path: The path to check (normalized, absolute or relative).
+        repo_root: Root of the aesop repo.
+        conductor_root: Root of the conductor3 directory.
+
+    Returns:
+        True if the path is under repo_root or conductor_root; False otherwise.
+    """
+    p = Path(path).resolve()
+    try:
+        p.relative_to(Path(repo_root).resolve())
+        return True
+    except ValueError:
+        pass
+
+    try:
+        p.relative_to(Path(conductor_root).resolve())
+        return True
+    except ValueError:
+        pass
+
+    return False
+
+
+def build_context_pack(
+    decision_type: str,
+    sources: Dict[str, Optional[str]],
+    repo_root: Optional[str] = None,
+    conductor_root: Optional[str] = None,
+    size_cap: int = 32768,
+    evidence: Optional[Dict[str, str]] = None,
+    evidence_cap: int = 4096,
+) -> ContextPack:
+    """Build a size-bounded context pack from allowlisted sources.
+
+    The orchestrator reads ONLY:
+      - STATE.md (the working plan/phase).
+      - BUILDLOG.md (append-only wave audit trail).
+      - MEMORY.md and similar control files (git-tracked state).
+      - state/tracker.json (work items).
+      - Explicitly passed files under the repo or conductor roots.
+      - Evidence excerpts (code snippets, repro output, etc.) passed explicitly.
+
+    Args:
+        decision_type: Name of the decision (e.g., 'rank_backlog').
+        sources: Dict mapping logical names to file paths or None.
+                 Recognized logical sources:
+                   'state' -> reads STATE.md from repo/conductor root.
+                   'buildlog_tail' -> last N lines of BUILDLOG.md.
+                   'tracker_open' -> open items subset of tracker.json.
+                   'brief:<path>' -> explicit path (must be under allowlist).
+
+        repo_root: Path to the aesop repo root. If None, uses cwd.
+        conductor_root: Path to conductor3 root. If None, assumes ~/conductor3.
+        size_cap: Size limit in bytes for main content (default 32KB). Truncation
+                  is deterministic (oldest-first for logs).
+        evidence: Optional dict mapping evidence_name -> evidence_text.
+                  Evidence must be passed explicitly (not read from arbitrary paths).
+                  Appended to pack under '[evidence]' section; size-bounded separately.
+        evidence_cap: Size limit in bytes for evidence content (default 4KB).
+                      Truncation is deterministic (truncate end of text).
+
+    Returns:
+        ContextPack with content dict + evidence dict + manifest.
+
+    Raises:
+        ContextPackViolation: if a source path violates the allowlist.
+    """
+    if repo_root is None:
+        repo_root = os.getcwd()
+    if conductor_root is None:
+        conductor_root = os.path.expanduser("~/conductor3")
+
+    pack = ContextPack(
+        decision_type=decision_type,
+        sources_requested=tuple(sources.keys()),
+        total_size_cap=size_cap,
+        evidence_size_cap=evidence_cap,
+    )
+
+    for source_name, source_spec in sources.items():
+        if not source_name:
+            continue
+
+        content_dict, manifest_entry = _read_source(
+            source_name, source_spec, repo_root, conductor_root
+        )
+
+        pack.content.update(content_dict)
+        pack.manifest.append(manifest_entry)
+        for text in content_dict.values():
+            pack.total_size_bytes += len(text.encode("utf-8"))
+
+    # Enforce size cap on main content: truncate oldest-first (log sources first).
+    if pack.total_size_bytes > pack.total_size_cap:
+        _truncate_pack(pack, pack.total_size_cap)
+
+    # Add evidence if provided (explicit, allowlist-only).
+    if evidence:
+        for evidence_name, evidence_text in evidence.items():
+            if not evidence_name:
+                continue
+
+            pack.evidence[evidence_name] = evidence_text
+            evidence_bytes = len(evidence_text.encode("utf-8"))
+            pack.evidence_size_bytes += evidence_bytes
+
+            pack.evidence_manifest.append(
+                {
+                    "name": evidence_name,
+                    "included": True,
+                    "truncated": False,
+                    "truncation_reason": None,
+                    "size_bytes": evidence_bytes,
+                }
+            )
+
+        # Enforce size cap on evidence: truncate end-of-text if needed.
+        if pack.evidence_size_bytes > pack.evidence_size_cap:
+            _truncate_evidence(pack, pack.evidence_size_cap)
+
+    return pack
+
+
+def _read_source(
+    source_name: str,
+    source_spec: Optional[str],
+    repo_root: str,
+    conductor_root: str,
+) -> Tuple[Dict[str, str], Dict]:
+    """Read one context source and return (content_dict, manifest_entry).
+
+    Args:
+        source_name: Logical name (e.g., 'state', 'buildlog_tail:50').
+        source_spec: File path or None (for implicit sources like 'state').
+        repo_root: Repo root path.
+        conductor_root: Conductor root path.
+
+    Returns:
+        (dict of {source_name: text}, manifest_entry dict)
+
+    Raises:
+        ContextPackViolation: if the path is not allowlisted.
+    """
+    manifest = {
+        "source": source_name,
+        "included": False,
+        "truncated": False,
+        "truncation_reason": None,
+        "size_bytes": 0,
+    }
+
+    # Implicit sources (no path given).
+    if source_name == "state":
+        # Read STATE.md from repo or conductor root.
+        state_file = Path(repo_root) / "STATE.md"
+        if not state_file.exists():
+            state_file = Path(conductor_root) / "STATE.md"
+        if state_file.exists():
+            try:
+                text = state_file.read_text(encoding="utf-8")
+                manifest["included"] = True
+                manifest["size_bytes"] = len(text.encode("utf-8"))
+                return {source_name: text}, manifest
+            except OSError as e:
+                return {source_name: f"Error reading STATE.md: {e}"}, manifest
+        else:
+            return {source_name: "STATE.md not found"}, manifest
+
+    elif source_name.startswith("buildlog_tail:"):
+        # Read last N lines of BUILDLOG.md.
+        parts = source_name.split(":", 1)
+        try:
+            tail_count = int(parts[1])
+        except (ValueError, IndexError):
+            tail_count = 20  # default
+
+        buildlog_file = Path(repo_root) / "BUILDLOG.md"
+        if not buildlog_file.exists():
+            buildlog_file = Path(conductor_root) / "BUILDLOG.md"
+
+        if buildlog_file.exists():
+            try:
+                content = buildlog_file.read_text(encoding="utf-8")
+                # Split into lines (preserving empty lines except trailing).
+                all_lines = content.split("\n")
+                # Remove last empty line if file ended with newline.
+                if all_lines and all_lines[-1] == "":
+                    all_lines = all_lines[:-1]
+                # Take last N lines.
+                tail_lines = all_lines[-tail_count:] if tail_count > 0 else all_lines
+                text = "\n".join(tail_lines)
+                manifest["included"] = True
+                manifest["size_bytes"] = len(text.encode("utf-8"))
+                return {source_name: text}, manifest
+            except OSError as e:
+                return {source_name: f"Error reading BUILDLOG.md: {e}"}, manifest
+        else:
+            return {source_name: "BUILDLOG.md not found"}, manifest
+
+    elif source_name == "tracker_open":
+        # Read open items from state/tracker.json.
+        tracker_file = Path(repo_root) / "state" / "tracker.json"
+        if not tracker_file.exists():
+            tracker_file = Path(conductor_root) / "state" / "tracker.json"
+
+        if tracker_file.exists():
+            try:
+                with open(tracker_file, encoding="utf-8") as f:
+                    tracker_data = json.load(f)
+                # Extract open items (status != 'closed' or similar).
+                open_items = [
+                    item
+                    for item in tracker_data.get("items", [])
+                    if item.get("status") != "closed"
+                ]
+                text = json.dumps(open_items, indent=2, ensure_ascii=True)
+                manifest["included"] = True
+                manifest["size_bytes"] = len(text.encode("utf-8"))
+                return {source_name: text}, manifest
+            except (OSError, json.JSONDecodeError) as e:
+                return {
+                    source_name: f"Error reading tracker_open: {e}"
+                }, manifest
+        else:
+            return {source_name: "tracker.json not found"}, manifest
+
+    elif source_name.startswith("brief:"):
+        # Explicit file path (must be allowlisted).
+        path_spec = source_name[6:]  # Remove 'brief:' prefix.
+        if not path_spec:
+            raise ContextPackViolation(
+                f"brief: source has no path: {source_name}"
+            )
+
+        # Resolve ONCE, validate the RESOLVED path, then read that exact path.
+        # (Resolving separately for the check and the read is a TOCTOU window:
+        # a symlink swap between the two resolves could redirect the read
+        # outside the allowlist.)
+        brief_file = Path(path_spec).resolve()
+        if not _is_allowed_path(str(brief_file), repo_root, conductor_root):
+            raise ContextPackViolation(
+                f"brief:{path_spec} is not under allowlisted roots "
+                f"({repo_root}, {conductor_root})"
+            )
+        if brief_file.exists():
+            try:
+                text = brief_file.read_text(encoding="utf-8")
+                manifest["included"] = True
+                manifest["size_bytes"] = len(text.encode("utf-8"))
+                return {source_name: text}, manifest
+            except OSError as e:
+                return {source_name: f"Error reading {path_spec}: {e}"}, manifest
+        else:
+            return {source_name: f"File not found: {path_spec}"}, manifest
+
+    else:
+        # Unknown source type (not allowlisted).
+        raise ContextPackViolation(
+            f"Unknown context source '{source_name}'; "
+            f"allowed: 'state', 'buildlog_tail:N', 'tracker_open', 'brief:<path>'"
+        )
+
+
+def _truncate_pack(pack: ContextPack, size_cap: int) -> None:
+    """Truncate pack content to fit within size_cap.
+
+    Truncates oldest-first (log sources: buildlog_tail before state).
+    Mutates pack.content and pack.manifest in place.
+
+    Args:
+        pack: The context pack to truncate.
+        size_cap: The target size limit in bytes.
+    """
+    # Sort manifest by source type: logs (buildlog_tail) first, then others.
+    log_sources = [
+        m for m in pack.manifest if m["source"].startswith("buildlog_tail")
+    ]
+    other_sources = [
+        m for m in pack.manifest if not m["source"].startswith("buildlog_tail")
+    ]
+    sorted_manifest = log_sources + other_sources
+
+    # Truncate from log sources first, aggressively.
+    for manifest_entry in sorted_manifest:
+        if pack.total_size_bytes <= size_cap:
+            break
+
+        source_name = manifest_entry["source"]
+        if source_name not in pack.content:
+            continue
+
+        text = pack.content[source_name]
+        current_size = len(text.encode("utf-8"))
+
+        # For buildlog_tail, drop oldest lines (beginning of text).
+        if source_name.startswith("buildlog_tail"):
+            lines = text.split("\n")
+            # Aggressively reduce: start with 50% of lines, then 25%, etc.
+            best_text = text
+            best_size = current_size
+            for reduction in [2, 4, 10, 100]:
+                target_lines = max(1, len(lines) // reduction)
+                new_text = "\n".join(lines[-target_lines:])
+                new_size = len(new_text.encode("utf-8"))
+                # Accept this reduction if it helps us get closer to the cap.
+                if new_size < best_size:
+                    best_text = new_text
+                    best_size = new_size
+                if pack.total_size_bytes - current_size + new_size <= size_cap:
+                    break
+
+            pack.content[source_name] = best_text
+            pack.total_size_bytes -= current_size - best_size
+            # Manifest honesty: only claim truncation if content actually shrank.
+            if best_size < current_size:
+                manifest_entry["truncated"] = True
+                manifest_entry["truncation_reason"] = "size_cap_exceeded"
+            manifest_entry["size_bytes"] = best_size
+
+        # For other sources, truncate end of text.
+        elif pack.total_size_bytes > size_cap:
+            best_text = text
+            best_size = current_size
+            for reduction in [2, 4, 10, 100]:
+                target_size = max(100, current_size // reduction)
+                new_text = text[:target_size] + "\n... TRUNCATED ..."
+                new_size = len(new_text.encode("utf-8"))
+                # Accept this reduction if it helps us get closer to the cap.
+                if new_size < best_size:
+                    best_text = new_text
+                    best_size = new_size
+                if pack.total_size_bytes - current_size + new_size <= size_cap:
+                    break
+
+            pack.content[source_name] = best_text
+            pack.total_size_bytes -= current_size - best_size
+            # Manifest honesty: only claim truncation if content actually shrank.
+            if best_size < current_size:
+                manifest_entry["truncated"] = True
+                manifest_entry["truncation_reason"] = "size_cap_exceeded"
+            manifest_entry["size_bytes"] = best_size
+
+
+def _truncate_evidence(pack: ContextPack, size_cap: int) -> None:
+    """Truncate evidence content to fit within size_cap.
+
+    Truncates end-of-text for each evidence item (newest first, then oldest).
+    Mutates pack.evidence and pack.evidence_manifest in place.
+
+    Args:
+        pack: The context pack with evidence to truncate.
+        size_cap: The target size limit in bytes for evidence.
+    """
+    # Truncate evidence items (reverse order: newest/last-added first).
+    for manifest_entry in reversed(pack.evidence_manifest):
+        if pack.evidence_size_bytes <= size_cap:
+            break
+
+        evidence_name = manifest_entry["name"]
+        if evidence_name not in pack.evidence:
+            continue
+
+        text = pack.evidence[evidence_name]
+        current_size = len(text.encode("utf-8"))
+
+        # Truncate end of text.
+        best_text = text
+        best_size = current_size
+        for reduction in [2, 4, 10, 100]:
+            target_size = max(100, current_size // reduction)
+            new_text = text[:target_size] + "\n... TRUNCATED ..."
+            new_size = len(new_text.encode("utf-8"))
+            # Accept this reduction if it helps us get closer to the cap.
+            if new_size < best_size:
+                best_text = new_text
+                best_size = new_size
+            if pack.evidence_size_bytes - current_size + new_size <= size_cap:
+                break
+
+        pack.evidence[evidence_name] = best_text
+        pack.evidence_size_bytes -= current_size - best_size
+        # Manifest honesty: only claim truncation if content actually shrank.
+        if best_size < current_size:
+            manifest_entry["truncated"] = True
+            manifest_entry["truncation_reason"] = "evidence_size_cap_exceeded"
+        manifest_entry["size_bytes"] = best_size

package/driver/openai_compatible_driver.py

@@ -29,12 +29,19 @@ from agent_driver import (  # noqa: E402
     ROLE_VERIFY,
     ROLE_WORKER,
 )
+from backend_config import (  # noqa: E402
+    validate_base_url,
+    validate_is_local_base_url,
+)
 from codex_driver import CodexDriver  # noqa: E402
-from openai_transport import _AuthStripRedirectHandler  # noqa: E402
+from openai_transport import _AuthStripRedirectHandler, MAX_RESPONSE_SIZE  # noqa: E402
 
 
 def make_openai_compatible_transport(
-    base_url: str, api_key_env: str = "OPENAI_API_KEY", timeout_s: float = 120.0
+    base_url: str,
+    api_key_env: str = "OPENAI_API_KEY",
+    timeout_s: float = 120.0,
+    is_local: bool = False,
 ):
     """Factory function: return a transport callable for an OpenAI-compatible endpoint.
 
@@ -42,27 +49,40 @@ def make_openai_compatible_transport(
         base_url: e.g. "https://openrouter.ai/api/v1", "http://localhost:11434/v1"
         api_key_env: environment variable name for the API key (default "OPENAI_API_KEY")
         timeout_s: HTTP timeout in seconds
+        is_local: if True, a missing API key is replaced by a dummy Bearer
+            instead of raising. Requires a loopback base_url (validated here):
+            the key waiver keys off this VALIDATED flag, never off the URL
+            text (a substring check is spoofable, e.g. "localhost.attacker.example").
 
     Returns:
         A transport callable (payload dict) -> dict matching the CodexDriver contract.
 
     Raises:
-        RuntimeError: if the API key env var is not set (unless base_url suggests local Ollama).
+        ValueError: if is_local=True with a non-loopback base_url.
+        RuntimeError: at call time, if the API key env var is not set and
+            is_local is False (no URL-based waiver).
     """
     import urllib.error
     import urllib.request
 
+    # is_local waives the key requirement, so pin it to loopback at the
+    # factory too (defense in depth for direct factory callers).
+    if is_local:
+        validate_is_local_base_url(base_url)
+
     def transport(payload: dict) -> dict:
         """POST to the OpenAI-compatible endpoint via urllib."""
-        # For local Ollama, the API key may be unused/dummy; for hosted services, get it.
-        # The pattern os.environ.get("OPENAI_API_KEY") does not trigger secret_scan
-        # because the RHS contains dots/parens; we use a variable for flexibility.
+        # For validated-local endpoints the API key may be unused/dummy; for
+        # everything else it is required. The waiver is gated on the
+        # loopback-validated is_local flag ONLY -- never on the URL text.
         retrieved_key = os.environ.get(api_key_env)
-        if not retrieved_key and "localhost" not in base_url.lower():
+        if not retrieved_key and not is_local:
             raise RuntimeError(
                 f"{api_key_env} environment variable is not set, and "
-                f"base_url '{base_url}' does not look like localhost. "
-                f"Set {api_key_env} before running, or use a FakeTransport in tests."
+                f"base_url '{base_url}' is not a validated local endpoint "
+                f"(is_local). Set {api_key_env} before running, set "
+                f"is_local=True for a loopback endpoint, or use a "
+                f"FakeTransport in tests."
             )
 
         # Use dummy key for local Ollama if not set.
@@ -89,7 +109,16 @@ def make_openai_compatible_transport(
             opener = urllib.request.build_opener(_AuthStripRedirectHandler())
             with opener.open(request, timeout=timeout_s) as response:
                 status = response.status
-                body = response.read().decode("utf-8")
+                # Cap response read at MAX_RESPONSE_SIZE bytes before parsing.
+                # Read MAX_RESPONSE_SIZE+1 bytes to detect if response exceeds limit.
+                body_bytes = response.read(MAX_RESPONSE_SIZE + 1)
+                if len(body_bytes) > MAX_RESPONSE_SIZE:
+                    raise RuntimeError(
+                        f"Response size limit exceeded: {len(body_bytes)} bytes > "
+                        f"{MAX_RESPONSE_SIZE} bytes ({MAX_RESPONSE_SIZE // 1024}KB). "
+                        f"The response is too large."
+                    )
+                body = body_bytes.decode("utf-8")
 
             # Classify non-2xx as an error.
             if not (200 <= status < 300):
@@ -144,7 +173,9 @@ class OpenAICompatibleDriver(CodexDriver):
             api_key_env: Environment variable name for API key (default "OPENAI_API_KEY").
                 For local Ollama, can be unused/dummy.
             is_local: If True, marks this as a local/small model and sets verification tier to 3.
-                Default False (hosted models -> tier 2).
+                Default False (hosted models -> tier 2). Requires a loopback base_url
+                (localhost/127.0.0.1/::1): is_local disables the key requirement, so a
+                remote base_url is rejected at construction (ValueError).
             model_map: Optional role-to-model mapping for setup/verify roles (default=None, uses role-based fallback).
             transport: Optional injectable transport callable for testing (default=None, builds from base_url).
             now: callable returning time.time() for testing (default=time.time).
@@ -152,6 +183,16 @@ class OpenAICompatibleDriver(CodexDriver):
             max_retries: max in-turn retries on malformed JSON (default 2).
             timeout_s: HTTP timeout in seconds (default 120).
         """
+        # SSRF guard: validate base_url UNCONDITIONALLY at construction
+        # (parity with OpenAICompatibleOrchestratorBackend.__init__), so a
+        # direct construction with a private/link-local address fails even
+        # when the config-layer checks were bypassed.
+        validate_base_url(base_url)
+        # is_local disables the API-key requirement, so it must be pinned to
+        # a loopback base_url (parity with the orchestrator seat + config
+        # layer): is_local + remote would ship prompts with a dummy Bearer.
+        if is_local:
+            validate_is_local_base_url(base_url)
         self._base_url = base_url
         self._model = model
         self._api_key_env = api_key_env
@@ -163,6 +204,7 @@ class OpenAICompatibleDriver(CodexDriver):
                 base_url=base_url,
                 api_key_env=api_key_env,
                 timeout_s=timeout_s,
+                is_local=is_local,
             )
 
         # If no model_map provided, use a simple single-model fallback.

package/driver/openai_transport.py

@@ -26,6 +26,10 @@ import urllib.request
 # Type alias documenting the transport callable contract.
 Transport = callable  # (payload: dict) -> dict
 
+# Maximum response size (100 KB) to prevent OOM from hostile/broken endpoints.
+# Enforced at the read() level BEFORE parsing to fail-safe on excessive responses.
+MAX_RESPONSE_SIZE = 100 * 1024  # 100KB in bytes
+
 
 class _AuthStripRedirectHandler(urllib.request.HTTPRedirectHandler):
     """Custom redirect handler that strips Authorization on cross-origin redirects.
@@ -84,7 +88,10 @@ class _AuthStripRedirectHandler(urllib.request.HTTPRedirectHandler):
 
 
 def default_openai_transport(
-    payload: dict, timeout_s: float = 120.0, base_url: str = "https://api.openai.com/v1"
+    payload: dict,
+    timeout_s: float = 120.0,
+    base_url: str = "https://api.openai.com/v1",
+    api_key: str = None,
 ) -> dict:
     """Default transport: POST to OpenAI Chat Completions via urllib.
 
@@ -92,19 +99,24 @@ def default_openai_transport(
         payload: OpenAI Chat Completions request body (messages, model, etc.).
         timeout_s: HTTP timeout in seconds (default 120).
         base_url: OpenAI API base URL (default production).
+        api_key: Optional pre-resolved API key (HS-1 seats: callers that honor
+            a configured api_key_env or an is_local dummy key pass it here).
+            When None, falls back to reading OPENAI_API_KEY from the
+            environment (the legacy behavior, unchanged).
 
     Returns:
         Parsed JSON response (choices, usage, etc.).
 
     Raises:
-        RuntimeError: if OPENAI_API_KEY env var is not set, or if the HTTP
-            status is not 200-299.
+        RuntimeError: if no api_key was given and OPENAI_API_KEY env var is
+            not set, or if the HTTP status is not 200-299.
         urllib.error.URLError: if the HTTP request fails.
     """
-    # Read API key at call time from environment; NEVER hardcoded.
-    # The pattern os.environ.get("OPENAI_API_KEY") does not trigger secret_scan
-    # because the RHS contains dots/parens.
-    api_key = os.environ.get("OPENAI_API_KEY")
+    # Read API key at call time from environment (unless pre-resolved by the
+    # caller); NEVER hardcoded. The pattern os.environ.get("OPENAI_API_KEY")
+    # does not trigger secret_scan because the RHS contains dots/parens.
+    if not api_key:
+        api_key = os.environ.get("OPENAI_API_KEY")
     if not api_key:
         raise RuntimeError(
             "OPENAI_API_KEY environment variable is not set. "
@@ -130,7 +142,16 @@ def default_openai_transport(
         opener = urllib.request.build_opener(_AuthStripRedirectHandler())
         with opener.open(request, timeout=timeout_s) as response:
             status = response.status
-            body = response.read().decode("utf-8")
+            # Cap response read at MAX_RESPONSE_SIZE bytes before parsing.
+            # Read MAX_RESPONSE_SIZE+1 bytes to detect if response exceeds limit.
+            body_bytes = response.read(MAX_RESPONSE_SIZE + 1)
+            if len(body_bytes) > MAX_RESPONSE_SIZE:
+                raise RuntimeError(
+                    f"Response size limit exceeded: {len(body_bytes)} bytes > "
+                    f"{MAX_RESPONSE_SIZE} bytes ({MAX_RESPONSE_SIZE // 1024}KB). "
+                    f"The response is too large."
+                )
+            body = body_bytes.decode("utf-8")
 
         # Classify non-2xx as an error.
         if not (200 <= status < 300):
@@ -148,8 +169,8 @@ def default_openai_transport(
         error_message = None
         if exc.fp:
             try:
-                # Read bounded response body (~500 bytes) to avoid memory issues.
-                error_body = exc.fp.read(500).decode("utf-8", errors="replace")
+                # Read bounded response body (cap at MAX_RESPONSE_SIZE).
+                error_body = exc.fp.read(MAX_RESPONSE_SIZE + 1).decode("utf-8", errors="replace")
                 error_data = json.loads(error_body)
                 if isinstance(error_data, dict) and "error" in error_data:
                     error_obj = error_data["error"]