painapple-code 1.0.0__py3-none-any.whl

painapple_code/routes/api_upload.py

@@ -0,0 +1,293 @@
+"""
+Upload API Routes - Image and file upload endpoints
+
+These endpoints provide:
+- Image upload with automatic resizing for Claude
+- File upload to session uploads directory
+"""
+
+import base64
+import io
+import logging
+import secrets
+import time
+import warnings
+from pathlib import Path, PurePosixPath
+
+from fastapi import APIRouter, HTTPException, UploadFile, File
+from PIL import Image
+
+from painapple_code.session_store import SessionStore
+from painapple_code.paths import DATA_HOME
+from painapple_code.utils.file_paths import is_reserved_dos_name
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(tags=["upload"])
+
+# Image processing constants
+IMAGE_TYPES = {
+    'image/png': 'png',
+    'image/jpeg': 'jpeg',
+    'image/gif': 'gif',
+    'image/webp': 'webp',
+}
+
+MAX_IMAGE_SIZE = 20 * 1024 * 1024  # 20MB upload limit
+MAX_IMAGE_DIMENSION = 1568  # Claude's recommended max
+TARGET_FILE_SIZE = 1 * 1024 * 1024  # Target ~1MB after processing
+
+# Decompression-bomb ceiling, in PIXELS — the byte cap above cannot bound this.
+# PNG/WebP compress uniform data extremely well, so a ~100KB file can declare
+# 30000x30000 and decode to gigabytes of RGBA. Pillow's default (~89M px) only
+# *warns* and keeps decoding, and it raises only past 2x that, so relying on the
+# default means the allocation happens first. 50M px (~200MB RGBA) is far above
+# any real screenshot or photo and well under what hurts.
+Image.MAX_IMAGE_PIXELS = 50_000_000
+
+# Promote Pillow's DecompressionBombWarning to an exception so the guard is a
+# refusal rather than a log line someone reads afterwards. The upload path
+# already converts exceptions into a 400.
+warnings.simplefilter('error', Image.DecompressionBombWarning)
+
+MAX_FILE_SIZE = 10 * 1024 * 1024  # 10MB limit for file uploads
+
+
+def resize_image_for_claude(image_data: bytes, content_type: str) -> tuple[bytes, str, dict]:
+    """Resize image if needed for optimal Claude processing."""
+    img = Image.open(io.BytesIO(image_data))
+    original_size = len(image_data)
+    original_dimensions = img.size
+
+    if img.mode == 'RGBA':
+        output_format = 'PNG'
+        output_media_type = 'image/png'
+    else:
+        if img.mode != 'RGB':
+            img = img.convert('RGB')
+        output_format = 'JPEG'
+        output_media_type = 'image/jpeg'
+
+    width, height = img.size
+    if width > MAX_IMAGE_DIMENSION or height > MAX_IMAGE_DIMENSION:
+        ratio = min(MAX_IMAGE_DIMENSION / width, MAX_IMAGE_DIMENSION / height)
+        new_size = (int(width * ratio), int(height * ratio))
+        img = img.resize(new_size, Image.Resampling.LANCZOS)
+        logger.info(f"Resized image from {original_dimensions} to {new_size}")
+
+    output = io.BytesIO()
+    if output_format == 'JPEG':
+        img.save(output, format=output_format, quality=85, optimize=True)
+    else:
+        img.save(output, format=output_format, optimize=True)
+
+    processed_data = output.getvalue()
+
+    stats = {
+        "original_size": original_size,
+        "processed_size": len(processed_data),
+        "original_dimensions": original_dimensions,
+        "final_dimensions": img.size,
+        "compression_ratio": round(original_size / len(processed_data), 2) if len(processed_data) > 0 else 1
+    }
+
+    return processed_data, output_media_type, stats
+
+
+@router.post("/api/upload-image")
+async def upload_image(file: UploadFile = File(...), session: str = None):
+    """Upload an image and return it as base64 for sending to Claude.
+    Also saves the processed image to disk for persistence across page refresh."""
+    content_type = file.content_type
+    if content_type not in IMAGE_TYPES:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Unsupported image type: {content_type}. Supported: {list(IMAGE_TYPES.keys())}"
+        )
+
+    content = await file.read()
+
+    if len(content) > MAX_IMAGE_SIZE:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Image too large: {len(content)} bytes. Max: {MAX_IMAGE_SIZE} bytes"
+        )
+
+    try:
+        processed_data, media_type, stats = resize_image_for_claude(content, content_type)
+    except Exception as e:
+        logger.error(f"Image processing failed: {e}")
+        raise HTTPException(status_code=400, detail=f"Failed to process image: {str(e)}")
+
+    b64_data = base64.standard_b64encode(processed_data).decode('utf-8')
+
+    # Save processed image to disk for persistence across page refresh
+    ext = 'png' if media_type == 'image/png' else 'jpg'
+    stored_name = f"img_{int(time.time())}_{secrets.token_hex(4)}.{ext}"
+
+    if session and SessionStore.exists(session):
+        uploads_dir = SessionStore.get_uploads_path(session)
+    else:
+        uploads_dir = DATA_HOME / "uploads" / "tmp"
+        uploads_dir.mkdir(parents=True, exist_ok=True)
+
+    try:
+        (uploads_dir / stored_name).write_bytes(processed_data)
+    except Exception as e:
+        logger.warning(f"Failed to persist uploaded image to disk: {e}")
+        # Non-fatal — image still works in-memory, just won't survive refresh
+        stored_name = None
+
+    logger.info(f"Uploaded image: {file.filename}, "
+                f"original={stats['original_size']/1024:.1f}KB {stats['original_dimensions']}, "
+                f"processed={stats['processed_size']/1024:.1f}KB {stats['final_dimensions']}, "
+                f"compression={stats['compression_ratio']}x"
+                f"{f', stored={stored_name}' if stored_name else ''}")
+
+    return {
+        "success": True,
+        "filename": file.filename,
+        "stored_name": stored_name,
+        "media_type": media_type,
+        "original_size": stats["original_size"],
+        "processed_size": stats["processed_size"],
+        "dimensions": stats["final_dimensions"],
+        "compression_ratio": stats["compression_ratio"],
+        "image": {
+            "type": "image",
+            "source": {
+                "type": "base64",
+                "media_type": media_type,
+                "data": b64_data
+            }
+        }
+    }
+
+
+# Longest filename we hand to the filesystem. NAME_MAX is 255 on ext4 and
+# NTFS; 200 leaves room for the "-2", "-3" de-duplication suffixes callers
+# append.
+_MAX_NAME_LEN = 200
+
+
+def _truncate_name(name: str) -> str:
+    """Clamp to _MAX_NAME_LEN, keeping the extension when one can fit.
+
+    PurePosixPath, not Path, for the same reason as the basename split
+    below: nothing here should vary with the host OS. (No separators or
+    colons survive to this point, so the two flavors agree — but pinning
+    it keeps that true if the rules above ever change.)
+
+    The old form was `name[:200 - len(ext)] + ext`, which for any suffix
+    longer than 200 made the slice bound negative — `name[:-51]` chops the
+    WRONG end and still returns an over-limit name (a 256-char input came
+    back 251 chars). A suffix that alone busts the budget isn't an
+    extension in any useful sense, so it gets clamped like any other text.
+    """
+    if len(name) <= _MAX_NAME_LEN:
+        return name
+    ext = PurePosixPath(name).suffix
+    if len(ext) > _MAX_NAME_LEN:
+        return name[:_MAX_NAME_LEN]
+    return PurePosixPath(name).stem[:_MAX_NAME_LEN - len(ext)] + ext
+
+
+def sanitize_filename(filename: str) -> str:
+    """Sanitize a filename to prevent path traversal and other issues."""
+    if not filename:
+        raise ValueError("Empty filename")
+
+    # Basename under BOTH path flavors, not whichever one the host happens to
+    # be. `Path(filename).name` was platform-dependent in a way that changed
+    # the result: WindowsPath("a:b.txt").name is "b.txt" — it reads "a:" as a
+    # drive — while PosixPath's is "a:b.txt". So the same upload landed under
+    # a different name depending on the server's OS, and the colon rule below
+    # only ran on one of them. Splitting on both separators here makes every
+    # platform agree (and "a:b.txt" reaches the ':' rule everywhere).
+    filename = filename.replace('\\', '/').rsplit('/', 1)[-1]
+    filename = "".join(c for c in filename if c.isprintable() and c not in '\x00')
+
+    # NTFS forbids these outright; without stripping them the write fails
+    # with an opaque OSError instead of a clean rejection.
+    filename = "".join('_' if c in ':*?"<>|' else c for c in filename)
+
+    # NTFS silently strips trailing dots and spaces, so "report." and
+    # "report" become the same file — a quiet overwrite of someone else's
+    # upload, and a way to smuggle a second name past a uniqueness check.
+    filename = filename.rstrip(". ")
+
+    # Length first, reserved-device check AFTER it. The other order is what
+    # the comment here used to claim was safe ("before length truncation so
+    # that truncating can't create one") and it was exactly backwards:
+    # truncation is the step that CAN create one. `con` + 10 filler chars +
+    # a 197-char extension passed the guard on stem "conxxxxxxxxxx", then
+    # truncated to "con.yyy…" — a name Windows resolves to the CON console
+    # device, so the upload's write_bytes went to the console.
+    filename = _truncate_name(filename)
+    filename = filename.rstrip(". ")
+
+    # An alternate-data-stream suffix is gone with ':' above; device names
+    # need their own check. Shared with the read-path screen in
+    # utils.file_paths so the two can't disagree about what a device is —
+    # this file's private copy had already drifted, accepting "nul .txt"
+    # (Windows strips the trailing space and opens the device) that
+    # is_path_allowed_for_read denies.
+    #
+    # Applied on EVERY platform, not just win32: uploads are shared (synced
+    # dirs, a repo later cloned on Windows), and a Linux-hosted server
+    # shouldn't be able to mint a file its Windows users can't open.
+    if is_reserved_dos_name(filename):
+        # The prefix can push a just-at-limit name one over, so re-clamp.
+        # This can't loop: every truncation of "_…" still starts with "_",
+        # which is not a device name.
+        filename = _truncate_name("_" + filename).rstrip(". ")
+
+    if not filename or filename in ('.', '..'):
+        raise ValueError("Invalid filename after sanitization")
+
+    return filename
+
+
+@router.post("/api/upload-file")
+async def upload_file(file: UploadFile = File(...), session: str = None):
+    """Upload a file to the session's uploads directory (or temp dir if no session yet)."""
+    content = await file.read()
+
+    if len(content) > MAX_FILE_SIZE:
+        raise HTTPException(
+            status_code=400,
+            detail=f"File too large: {len(content)} bytes. Max: {MAX_FILE_SIZE} bytes (10MB)"
+        )
+
+    if len(content) == 0:
+        raise HTTPException(status_code=400, detail="Empty file")
+
+    try:
+        safe_name = sanitize_filename(file.filename)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+    # Use session uploads dir if available, otherwise a shared temp dir
+    if session and SessionStore.exists(session):
+        uploads_dir = SessionStore.get_uploads_path(session)
+    else:
+        uploads_dir = DATA_HOME / "uploads" / "tmp"
+        uploads_dir.mkdir(parents=True, exist_ok=True)
+
+    target_path = uploads_dir / safe_name
+
+    try:
+        target_path.write_bytes(content)
+    except Exception as e:
+        logger.error(f"Failed to write uploaded file: {e}")
+        raise HTTPException(status_code=500, detail="Failed to save file")
+
+    logger.info(f"Uploaded file: {file.filename} -> {target_path} ({len(content)} bytes)")
+
+    return {
+        "success": True,
+        "filename": file.filename,
+        "stored_name": safe_name,
+        "path": str(target_path.resolve()),
+        "size": len(content),
+    }

painapple_code/routes/api_viewer.py

@@ -0,0 +1,229 @@
+"""
+File Viewer API Routes - Raw file serving and full-screen file viewer
+
+These endpoints provide:
+- Raw file serving with correct MIME types (for images, etc.)
+- Full-screen file viewer page (images, markdown, code, excalidraw, charts)
+- Excalidraw JSON → SVG rendering via Node.js subprocess
+- Vega-Lite chart JSON → SVG rendering via Node.js subprocess
+"""
+
+import logging
+from typing import NoReturn
+
+from fastapi import APIRouter, HTTPException, Request
+from fastapi.responses import HTMLResponse, FileResponse, Response
+
+from painapple_code.utils.file_paths import is_path_allowed_for_read, safe_resolve
+from painapple_code.utils.excalidraw import render_excalidraw, render_excalidraw_file, is_excalidraw_file
+from painapple_code.utils.chart import render_chart, render_chart_file, is_chart_file
+from painapple_code.viewer_templates import (
+    usage_page, access_denied_page, not_found_page, error_page,
+    image_viewer, markdown_viewer, code_viewer, get_language,
+    excalidraw_viewer, chart_viewer,
+)
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(tags=["viewer"])
+
+
+# MIME types for common file extensions
+MIME_TYPES = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.svg': 'image/svg+xml',
+    '.ico': 'image/x-icon',
+    '.pdf': 'application/pdf',
+    '.md': 'text/markdown',
+    '.txt': 'text/plain',
+    '.json': 'application/json',
+    '.xml': 'application/xml',
+    '.py': 'text/x-python',
+    '.js': 'text/javascript',
+    '.ts': 'text/typescript',
+    '.html': 'text/html',
+    '.css': 'text/css',
+    '.sh': 'text/x-shellscript',
+    '.yaml': 'text/yaml',
+    '.yml': 'text/yaml',
+    '.toml': 'text/toml',
+}
+
+IMAGE_SUFFIXES = {'.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg'}
+
+# SVG is a scriptable format. These endpoints render SVG from model- or
+# repo-authored specs and serve it same-origin, so a top-level navigation to
+# one of them would otherwise run its script in the server origin. Forcing an
+# opaque origin (sandbox with no allow-same-origin) removes that: the document
+# can neither read the auth cookie nor issue credentialed same-origin calls.
+# Mirrors the policy api_browser.py applies to proxied/local HTML and SVG.
+# Harmless for the normal consumption paths — browsers ignore CSP on image
+# subresources (<img src>), and fetch()+innerHTML never applies it as a policy.
+_SVG_SECURITY_HEADERS = {
+    'Content-Security-Policy': "sandbox allow-scripts allow-forms",
+    'X-Content-Type-Options': 'nosniff',
+}
+
+
+def _renderers_enabled(request: Request) -> bool:
+    """Server-side chart/excalidraw rendering gate. Defaults to False (secure)
+    when unset — e.g. under a bare TestClient that never ran server.main()."""
+    return bool(getattr(request.app.state, "renderers_enabled", False))
+
+
+def _reject_renderer_disabled() -> NoReturn:
+    """Refuse when rendering is off. Never spawns the Node subprocess, so the
+    model-authored-spec SSRF/file-read vector cannot fire. Always raises."""
+    raise HTTPException(status_code=503, detail="Server-side rendering is disabled")
+
+
+@router.get("/api/file-raw")
+async def get_file_raw(request: Request, path: str, dark: bool = False):
+    """Serve a raw file with correct MIME type (for images, etc.)."""
+    try:
+        p = safe_resolve(path)
+
+        if not is_path_allowed_for_read(p):
+            raise HTTPException(status_code=403, detail="Path not allowed")
+        if not p.exists():
+            raise HTTPException(status_code=404, detail="File not found")
+        if not p.is_file():
+            raise HTTPException(status_code=400, detail="Not a file")
+
+        suffix = p.suffix.lower()
+
+        # Server-side rendering is gated: when disabled, fall through to raw
+        # serving so the Node renderer is never invoked (SSRF/file-read guard).
+        renderers_on = _renderers_enabled(request)
+
+        # Excalidraw files: render to SVG on-the-fly (.excalidraw or .excalidraw.md)
+        if renderers_on and is_excalidraw_file(p):
+            try:
+                svg_content = await render_excalidraw_file(p, dark_mode=dark)
+                return Response(
+                    content=svg_content,
+                    media_type='image/svg+xml',
+                    headers={'Cache-Control': 'no-cache', **_SVG_SECURITY_HEADERS},
+                )
+            except Exception as e:
+                logger.error("Excalidraw render failed for %s: %s", p, e)
+                raise HTTPException(status_code=500, detail=f"Render failed: {e}")
+
+        # Vega-Lite chart files: render to SVG on-the-fly (.vl.json)
+        if renderers_on and is_chart_file(p):
+            try:
+                svg_content = await render_chart_file(p, dark_mode=dark)
+                return Response(
+                    content=svg_content,
+                    media_type='image/svg+xml',
+                    headers={'Cache-Control': 'no-cache', **_SVG_SECURITY_HEADERS},
+                )
+            except Exception as e:
+                logger.error("Chart render failed for %s: %s", p, e)
+                raise HTTPException(status_code=500, detail=f"Render failed: {e}")
+
+        mime_type = MIME_TYPES.get(suffix, 'application/octet-stream')
+
+        return FileResponse(
+            path=str(p),
+            media_type=mime_type,
+            filename=p.name,
+            headers={'Cache-Control': 'no-cache'},
+        )
+    except HTTPException:
+        raise
+    except PermissionError:
+        raise HTTPException(status_code=403, detail="Permission denied")
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.get("/view", response_class=HTMLResponse)
+async def file_viewer(path: str = None):
+    """Full-screen file viewer page (images, markdown, code)."""
+    if not path:
+        return usage_page()
+
+    try:
+        p = safe_resolve(path)
+
+        if not is_path_allowed_for_read(p):
+            return access_denied_page(path)
+
+        if not p.exists():
+            return not_found_page(path)
+
+        suffix = p.suffix.lower()
+
+        # Excalidraw viewer (.excalidraw or .excalidraw.md — must check before .md)
+        if is_excalidraw_file(p):
+            return excalidraw_viewer(p.name, str(p))
+
+        # Vega-Lite chart viewer (.vl.json — must check before generic .json)
+        if is_chart_file(p):
+            return chart_viewer(p.name, str(p))
+
+        # Image viewer
+        if suffix in IMAGE_SUFFIXES:
+            return image_viewer(p.name, str(p), str(p))
+
+        # Markdown viewer
+        if suffix == '.md':
+            content = p.read_text(encoding="utf-8", errors='replace')
+            return markdown_viewer(p.name, str(p), content)
+
+        # Code/text viewer
+        content = p.read_text(encoding="utf-8", errors='replace')
+        lang = get_language(suffix)
+        return code_viewer(p.name, str(p), content, lang)
+
+    except Exception as e:
+        return error_page(str(e))
+
+
+@router.post("/api/excalidraw/render")
+async def render_excalidraw_json(request: Request, dark: bool = False):
+    """Render excalidraw JSON body to SVG. Used for inline chat rendering."""
+    if not _renderers_enabled(request):
+        _reject_renderer_disabled()
+    try:
+        body = await request.body()
+        if not body:
+            raise HTTPException(status_code=400, detail="Empty body")
+        svg_content = await render_excalidraw(body, dark_mode=dark)
+        return Response(
+            content=svg_content,
+            media_type='image/svg+xml',
+            headers=_SVG_SECURITY_HEADERS,
+        )
+    except RuntimeError as e:
+        raise HTTPException(status_code=500, detail=str(e))
+    except Exception as e:
+        logger.error("Excalidraw render failed: %s", e)
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+@router.post("/api/chart/render")
+async def render_chart_json(request: Request, dark: bool = False):
+    """Render Vega-Lite JSON body to SVG. Used for inline chat rendering."""
+    if not _renderers_enabled(request):
+        _reject_renderer_disabled()
+    try:
+        body = await request.body()
+        if not body:
+            raise HTTPException(status_code=400, detail="Empty body")
+        svg_content = await render_chart(body, dark_mode=dark)
+        return Response(
+            content=svg_content,
+            media_type='image/svg+xml',
+            headers=_SVG_SECURITY_HEADERS,
+        )
+    except RuntimeError as e:
+        raise HTTPException(status_code=500, detail=str(e))
+    except Exception as e:
+        logger.error("Chart render failed: %s", e)
+        raise HTTPException(status_code=500, detail=str(e))

painapple_code/routes/dependencies.py

@@ -0,0 +1,109 @@
+"""Shared FastAPI dependencies for route modules.
+
+Pulls repeated "look up session, 404 if missing" boilerplate out of every
+endpoint that takes a {session_id} path parameter.
+"""
+
+from fastapi import HTTPException
+
+from painapple_code import paths
+from painapple_code.session_store import SessionStore
+
+
+def get_session_store(session_id: str) -> SessionStore:
+    """Resolve a {session_id} path param to its SessionStore, or 404."""
+    store, _ = SessionStore._find_session(session_id)
+    if store is None:
+        raise HTTPException(status_code=404, detail="Session not found")
+    return store
+
+
+def effective_default_provider(app):
+    """The provider NEW sessions get: the --default-provider server flag wins,
+    then the `default_provider` global-config key, then the registry default.
+    Mirrors the resolution ws_chat.py uses when creating a session."""
+    from painapple_code.providers import get_provider
+    agents = getattr(app.state, "agents", None)
+    name = (getattr(agents, "default_provider", None)
+            or paths.load_global_config().get("default_provider"))
+    return get_provider(name)
+
+
+def provider_enabled_map(app) -> dict:
+    """Which engines the picker offers: ``{provider_name: bool}``.
+
+    Per-engine resolution: `providers_enabled` config override if present,
+    else the provider's self-described `default_enabled`. The effective
+    default engine is always on — new sessions land on it, so hiding it
+    would strand the picker. This gates only UI listing; explicit selection
+    (``?provider=``, PUT) and already-bound sessions ignore it.
+    """
+    from painapple_code.providers import all_providers
+    overrides = paths.load_global_config().get("providers_enabled") or {}
+    default_name = effective_default_provider(app).name
+    return {
+        p.name: p.name == default_name or bool(overrides.get(p.name, p.default_enabled))
+        for p in all_providers()
+    }
+
+
+def bind_permission_level(stored_level, provider):
+    """Permission level to stamp when a session BINDS to `provider` (create
+    with an explicit engine, or an in-place switch) — or None to leave the
+    meta alone.
+
+    The effective level (session's stored one, else the app-wide default)
+    survives when the new engine speaks it. A cross-vocabulary value (e.g.
+    Claude's ``dontAsk`` landing on a Codex session) is re-anchored to the
+    engine's own default: launch would otherwise apply a silent back-compat
+    mapping the UI can't label, leaving the permission chip showing a mode
+    the engine doesn't have. Meta, UI, and launch must agree at bind time.
+    """
+    from painapple_code.providers import DEFAULT_PROVIDER, get_provider
+    if provider is None:
+        return None
+    effective = stored_level
+    if effective is None:
+        config = paths.load_global_config()
+        effective = (config.get("default_permission_level")
+                     or get_provider(DEFAULT_PROVIDER).default_permission_mode())
+    vocab = {m["value"] for m in provider.permission_modes() if m.get("value")}
+    if effective in vocab:
+        return None
+    return provider.default_permission_mode()
+
+
+def preferred_model_survives(stored_model, provider) -> bool:
+    """Whether a session's stored ``preferred_model`` still means something
+    after binding to `provider` (in-place engine switch) — False = clear it.
+
+    A model pick only makes sense to the engine whose catalog offered it: a
+    Claude id pinned on a session switching to Codex would be silently
+    dropped at launch (Codex forwards only its own ids) while the model chip
+    keeps labeling the stale pick — and the reverse would hand Claude an id
+    its API rejects. Clearing resets the session to the new engine's own
+    default. An engine with an EMPTY catalog (the app doesn't manage its
+    models) keeps the stored value — its launch path decides what to
+    forward. Prefix match, same as the UI: engine-reported ids carry date
+    suffixes ("claude-opus-4-6-20260105" is catalog id "claude-opus-4-6").
+
+    Membership is checked against `enabled_models()` — a model the user hid
+    in Settings isn't offered anywhere, so it can't survive as a default
+    either (the chip would label it "Default" while launch passed the hidden
+    id). The emptiness escape stays on the RAW catalog: all-models-hidden
+    means "offer nothing" (clear), not "unknown vocabulary" (keep).
+    """
+    if provider is None or not stored_model:
+        return True
+    if not any(m.get("id") for m in provider.models()):
+        return True
+    enabled_ids = [m.get("id") for m in provider.enabled_models() if m.get("id")]
+    return any(stored_model.startswith(mid) for mid in enabled_ids)
+
+
+def provider_is_locked(meta: dict) -> bool:
+    """A session's engine is frozen once it has run a turn — the conversation
+    lives in that engine's on-disk format (its provider_session_id means
+    nothing to another engine), so the provider is only switchable while the
+    session is still empty (no turns, no upstream session id)."""
+    return bool(meta.get("message_count", 0)) or bool(meta.get("provider_session_id"))