acm-context-management 0.2.0__tar.gz

acm_context_management-0.2.0/.gitignore

@@ -0,0 +1,10 @@
+# Python build artifacts
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.pyc
+.venv/
+
+# Local config copy (user edits; example is shipped)
+config/acm.config.json

acm_context_management-0.2.0/PACKAGING.md

@@ -0,0 +1,139 @@
+# Packaging & publishing
+
+The extension ships as **one PyPI distribution** — `acm-context-management` —
+exposing two console scripts: `acm-gateway` and `acm-mcp`. It is self-contained:
+the context-management engine is **vendored** into `acm_engine/_vendor/`, so an
+end user never needs the website's `../backend`.
+
+## Before you build: sync the vendored engine
+
+The vendored copy is committed, but refresh it whenever the engine changes in
+`backend/`:
+
+```bash
+cd extension
+python scripts/sync_engine.py     # copies the 3 modules into acm_engine/_vendor/
+git add acm_engine/_vendor && git commit -m "sync vendored engine"
+```
+
+## Build
+
+```bash
+cd extension
+uv build                          # -> dist/acm_context_management-0.2.0-py3-none-any.whl + .tar.gz
+```
+
+Confirm the wheel is self-contained (contains the vendored engine **and** the
+`visual_tool/` subpackage — without it the visual method breaks once installed):
+
+```bash
+python -m zipfile -l dist/acm_context_management-0.2.0-py3-none-any.whl | grep _vendor
+# acm_engine/_vendor/{context_profiles,context_editing,cache_layout,relevance,
+#   relevance_encoder}.py  +  acm_engine/_vendor/visual_tool/{rasterizer,indexer,__init__}.py
+```
+
+Smoke-test a clean install (run it from a directory **other** than `extension/`
+so it doesn't pick up the source tree):
+
+```bash
+uv venv /tmp/acmwheel --python 3.11
+uv pip install --python /tmp/acmwheel/bin/python dist/acm_context_management-0.2.0-py3-none-any.whl
+cd /tmp && /tmp/acmwheel/bin/python -c "from acm_gateway.app import app; \
+  from visual_tool.rasterizer import render_2col_pages; print('ok', len(render_2col_pages('x'*9000)), 'pages')"
+```
+
+## Publish to PyPI
+
+```bash
+uv publish                        # uses UV_PUBLISH_TOKEN or ~/.pypirc
+# first, test against TestPyPI:
+uv publish --publish-url https://test.pypi.org/legacy/
+```
+
+## How end users run it
+
+```bash
+# zero-install, ephemeral (uvx resolves the package, runs the script):
+uvx --from acm-context-management acm-gateway
+uvx --from acm-context-management acm-mcp
+
+# or install once:
+uv tool install acm-context-management
+acm-gateway        # http://127.0.0.1:8807
+acm-mcp            # stdio MCP server
+```
+
+Required env for the gateway upstream:
+
+```bash
+export ACM_UPSTREAM_BASE_URL=https://openrouter.ai/api/v1   # OpenAI-compatible
+export ACM_UPSTREAM_API_KEY=sk-or-v1-...
+# for the Anthropic /v1/messages surface (Claude Code):
+export ACM_ANTHROPIC_API_KEY=sk-ant-...
+```
+
+## Publish the VS Code extension (Open VSX + MS Marketplace)
+
+The webview UI ships as a `.vsix`. **Open VSX is the priority** — it's where
+Cursor / Windsurf / Antigravity (VS Code forks) install extensions; the MS
+Marketplace covers stock VS Code.
+
+```bash
+cd extension/adapters/vscode
+npm install                       # first time only
+npm run package                   # -> acm-context-management-0.2.0.vsix (runs vsce, bundles UI)
+```
+
+One-time setup before the first publish:
+
+- **Publisher id** — `package.json` uses `"publisher": "acm"`. Create that
+  publisher (or change the field to one you own) on **both** registries.
+- **Icon** — add a 128×128+ **PNG** at `media/icon.png` and set
+  `"icon": "media/icon.png"` in `package.json`. The marketplaces show a
+  placeholder without it (packaging still succeeds; this is listing quality).
+
+Publish:
+
+```bash
+# Open VSX (Cursor / Windsurf / Antigravity / VSCodium)
+#   token: https://open-vsx.org  ->  account  ->  Access Tokens
+npx ovsx publish acm-context-management-0.2.0.vsix -p "$OVSX_TOKEN"
+
+# MS Marketplace (stock VS Code)
+#   PAT: https://dev.azure.com  ->  Marketplace (manage) publisher
+npx @vscode/vsce publish --no-dependencies -p "$VSCE_TOKEN"
+```
+
+Local install for testing without publishing:
+
+```bash
+code --install-extension acm-context-management-0.2.0.vsix      # VS Code
+cursor --install-extension acm-context-management-0.2.0.vsix    # Cursor
+```
+
+## Docker (optional, for a hosted gateway)
+
+```dockerfile
+# extension/Dockerfile  (TODO(acm): add this file)
+FROM python:3.12-slim
+RUN pip install acm-context-management
+EXPOSE 8807
+ENV ACM_HOST=0.0.0.0
+CMD ["acm-gateway"]
+```
+
+Publish to GHCR: `docker build -t ghcr.io/<you>/acm-gateway . && docker push …`.
+
+## Versioning
+
+Bump `version` in `pyproject.toml` (single source). Tag releases
+`acm-ext-vX.Y.Z`. The VSCode extension has its own version in
+`adapters/vscode/package.json` and its own publish flow (see that folder's
+README — `vsce publish` + `ovsx publish`).
+
+## What is NOT on PyPI
+
+The IDE adapters (`adapters/claude-code`, `adapters/cursor`,
+`adapters/vscode`) are config/glue distributed via the repo and the VS
+Marketplace / Open VSX — not pip. Only the gateway + MCP server are Python
+distributions.

acm_context_management-0.2.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: acm-context-management
+Version: 0.2.0
+Summary: Context-management gateway + MCP server that brings the ACM techniques (trimming, summarisation, image-recall, memory) into any IDE
+Project-URL: Homepage, https://github.com/HarishanA21/agentic_context_management
+Project-URL: Repository, https://github.com/HarishanA21/agentic_context_management
+Author: ACM
+License: MIT
+Keywords: claude-code,context-management,cursor,gateway,ides,llm,mcp,vscode
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.110
+Requires-Dist: httpx>=0.27
+Requires-Dist: langchain-core>=0.3
+Requires-Dist: langchain>=0.3
+Requires-Dist: mcp>=1.2
+Requires-Dist: pillow>=10
+Requires-Dist: pydantic>=2
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: uvicorn[standard]>=0.29
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ACM Extension — context management for any IDE
+
+This folder is **self-contained**. It turns the context-management engine that
+already powers the website (in [`../backend`](../backend)) into something usable
+from VSCode, Cursor, Antigravity, Claude Code, and Windsurf — **without changing
+a single line of the website's code.**
+
+It reaches the IDEs through three surfaces (see
+[`../EXTENSION_PLAN.md`](../EXTENSION_PLAN.md) for the why):
+
+| Folder | Surface | What it is |
+|---|---|---|
+| `acm_gateway/` | **Gateway** | A local OpenAI/Anthropic-compatible proxy. The IDE talks to it as if it were the AI; it applies every technique on the wire, then forwards to the real provider. Full feature parity. |
+| `acm_mcp/` | **MCP** | An MCP server exposing `remember` / `recall` / `compact` / `set_profile` tools. Works in *every* MCP-capable IDE. |
+| `adapters/` | **Hooks + config** | Per-IDE glue: Claude Code hooks, Cursor `mcp.json`, VSCode notes. |
+| `acm_engine/` | — | Thin bridge that imports the techniques from `../backend` so there is **one** source of truth. |
+
+## How it reuses the website's engine
+
+`acm_engine/` puts `../backend` on `sys.path` and re-exports the pure technique
+functions (`trim_tool_results`, `summarise_old_messages`,
+`sliding_window_trim`, `evict_stale_images`, `annotate_cache_breakpoints`) plus
+the `Profile` schema. Nothing in `../backend` is edited. The website and the
+extension share the same code; fix a bug once, both benefit.
+
+## Quick start (gateway)
+
+```bash
+cd extension
+uv venv --python 3.11
+source .venv/bin/activate
+uv pip install -e .
+
+# point it at any OpenAI-compatible upstream (OpenRouter shown)
+export ACM_UPSTREAM_BASE_URL=https://openrouter.ai/api/v1
+export ACM_UPSTREAM_API_KEY=sk-or-v1-...
+
+acm-gateway            # serves http://127.0.0.1:8807
+```
+
+Then tell the IDE the AI lives at `http://127.0.0.1:8807/v1` (Cursor: custom
+OpenAI base URL; Claude Code: `ANTHROPIC_BASE_URL`).
+
+## Config
+
+A single [`config/acm.config.example.json`](config/acm.config.example.json)
+holds the active profile (which techniques are on). Copy it to
+`config/acm.config.json` and edit, or set `ACM_CONFIG` to its path. The schema
+is the website's `Profile` model — same presets (`minimal`, `long_chat`,
+`power_research`, `cheap_long`, `visual_recall`).
+
+## Status
+
+- **Gateway** — runnable. OpenAI (`/v1/chat/completions`) **and** Anthropic
+  (`/v1/messages`) surfaces; full technique pipeline (trim / summarise / sliding
+  window / image-evict / cache breakpoints / **visual method** — rasterise big
+  tool outputs to images); **manual message removal** (cascade-safe drop-list,
+  persisted to `~/.acm/dropped.json`); **multi-provider routing** (OpenAI /
+  OpenRouter / Google / Azure on the OpenAI surface, Anthropic native; creds in
+  `~/.acm/providers.json`; route by `x-acm-provider` header, `slug/model`
+  prefix, or default — Bedrock via OpenRouter since it needs AWS SigV4); control
+  plane (`/status`, `/profile`, `/memory`, `/compact`, `/conversations`,
+  `/messages*`, `/providers*`).
+- **MCP server** — runnable: memory (`remember`/`recall`), `compact`,
+  `set_profile`/`status`, manual removal (`list_messages`/`drop_message`/
+  `restore_message`), providers (`list_providers`/`add_provider`/
+  `set_default_provider`), **sub-agent** (`spawn_subagent`), and **JIT retrieval**
+  (`find_files`/`read_slice`/`grep_files`).
+- **Claude Code** — gateway + hooks (trim + memory) + MCP. Done.
+- **Cursor** — gateway + hooks (capture + **compact-on-stop**) + MCP. Done.
+- **VSCode** — full extension (Language Model Tools + `@acm` chat participant +
+  webview settings) talking to the gateway; MCP drop-in for Antigravity /
+  Windsurf. TypeScript is written but not yet `tsc`-compiled here (needs
+  `npm install` with `@types/vscode`).
+
+Remaining work is marked with `# TODO(acm)` / `TODO(acm)`: orphan-`tool_use`
+pruning on the Anthropic path, React components in the VSCode webview, and
+auto-starting the gateway from the extension.

acm_context_management-0.2.0/README.md

@@ -0,0 +1,78 @@
+# ACM Extension — context management for any IDE
+
+This folder is **self-contained**. It turns the context-management engine that
+already powers the website (in [`../backend`](../backend)) into something usable
+from VSCode, Cursor, Antigravity, Claude Code, and Windsurf — **without changing
+a single line of the website's code.**
+
+It reaches the IDEs through three surfaces (see
+[`../EXTENSION_PLAN.md`](../EXTENSION_PLAN.md) for the why):
+
+| Folder | Surface | What it is |
+|---|---|---|
+| `acm_gateway/` | **Gateway** | A local OpenAI/Anthropic-compatible proxy. The IDE talks to it as if it were the AI; it applies every technique on the wire, then forwards to the real provider. Full feature parity. |
+| `acm_mcp/` | **MCP** | An MCP server exposing `remember` / `recall` / `compact` / `set_profile` tools. Works in *every* MCP-capable IDE. |
+| `adapters/` | **Hooks + config** | Per-IDE glue: Claude Code hooks, Cursor `mcp.json`, VSCode notes. |
+| `acm_engine/` | — | Thin bridge that imports the techniques from `../backend` so there is **one** source of truth. |
+
+## How it reuses the website's engine
+
+`acm_engine/` puts `../backend` on `sys.path` and re-exports the pure technique
+functions (`trim_tool_results`, `summarise_old_messages`,
+`sliding_window_trim`, `evict_stale_images`, `annotate_cache_breakpoints`) plus
+the `Profile` schema. Nothing in `../backend` is edited. The website and the
+extension share the same code; fix a bug once, both benefit.
+
+## Quick start (gateway)
+
+```bash
+cd extension
+uv venv --python 3.11
+source .venv/bin/activate
+uv pip install -e .
+
+# point it at any OpenAI-compatible upstream (OpenRouter shown)
+export ACM_UPSTREAM_BASE_URL=https://openrouter.ai/api/v1
+export ACM_UPSTREAM_API_KEY=sk-or-v1-...
+
+acm-gateway            # serves http://127.0.0.1:8807
+```
+
+Then tell the IDE the AI lives at `http://127.0.0.1:8807/v1` (Cursor: custom
+OpenAI base URL; Claude Code: `ANTHROPIC_BASE_URL`).
+
+## Config
+
+A single [`config/acm.config.example.json`](config/acm.config.example.json)
+holds the active profile (which techniques are on). Copy it to
+`config/acm.config.json` and edit, or set `ACM_CONFIG` to its path. The schema
+is the website's `Profile` model — same presets (`minimal`, `long_chat`,
+`power_research`, `cheap_long`, `visual_recall`).
+
+## Status
+
+- **Gateway** — runnable. OpenAI (`/v1/chat/completions`) **and** Anthropic
+  (`/v1/messages`) surfaces; full technique pipeline (trim / summarise / sliding
+  window / image-evict / cache breakpoints / **visual method** — rasterise big
+  tool outputs to images); **manual message removal** (cascade-safe drop-list,
+  persisted to `~/.acm/dropped.json`); **multi-provider routing** (OpenAI /
+  OpenRouter / Google / Azure on the OpenAI surface, Anthropic native; creds in
+  `~/.acm/providers.json`; route by `x-acm-provider` header, `slug/model`
+  prefix, or default — Bedrock via OpenRouter since it needs AWS SigV4); control
+  plane (`/status`, `/profile`, `/memory`, `/compact`, `/conversations`,
+  `/messages*`, `/providers*`).
+- **MCP server** — runnable: memory (`remember`/`recall`), `compact`,
+  `set_profile`/`status`, manual removal (`list_messages`/`drop_message`/
+  `restore_message`), providers (`list_providers`/`add_provider`/
+  `set_default_provider`), **sub-agent** (`spawn_subagent`), and **JIT retrieval**
+  (`find_files`/`read_slice`/`grep_files`).
+- **Claude Code** — gateway + hooks (trim + memory) + MCP. Done.
+- **Cursor** — gateway + hooks (capture + **compact-on-stop**) + MCP. Done.
+- **VSCode** — full extension (Language Model Tools + `@acm` chat participant +
+  webview settings) talking to the gateway; MCP drop-in for Antigravity /
+  Windsurf. TypeScript is written but not yet `tsc`-compiled here (needs
+  `npm install` with `@types/vscode`).
+
+Remaining work is marked with `# TODO(acm)` / `TODO(acm)`: orphan-`tool_use`
+pruning on the Anthropic path, React components in the VSCode webview, and
+auto-starting the gateway from the extension.

acm_context_management-0.2.0/acm_engine/__init__.py

@@ -0,0 +1,124 @@
+"""Bridge to the website's context-management engine.
+
+This is the *one* place the extension reaches into ``../backend``. It puts the
+backend directory on ``sys.path`` and re-exports the **pure** technique
+functions plus the ``Profile`` schema, so the gateway and the website run the
+exact same code. Nothing in ``../backend`` is edited.
+
+Why only the pure functions? ``context_editing.apply_context_edits`` is
+LangGraph-specific — it calls ``agent.get_state`` / ``agent.update_state``. The
+gateway has no LangGraph agent; it has a plain list of messages off the wire.
+So we import the lower-level building blocks (which operate on a
+``List[BaseMessage]``) and the gateway's own ``pipeline.py`` orchestrates them
+in the same fixed order ``apply_context_edits`` uses.
+
+If an import here ever fails, it's almost always because ``../backend`` moved or
+a dependency in ``backend/requirements.txt`` isn't installed in this venv.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+# Two ways to find the engine, in priority order:
+#   1. The **vendored** copy shipped inside the wheel (acm_engine/_vendor/) —
+#      this is what an end user who `pip install`ed the package gets. Refresh it
+#      from backend with `python scripts/sync_engine.py`.
+#   2. The repo's ../backend tree — used during local dev so a checkout runs the
+#      live engine without a sync step.
+# Whichever wins is put on sys.path so the engine's flat imports
+# (`import context_profiles`, `from context_editing import ...`) resolve.
+_VENDOR = Path(__file__).resolve().parent / "_vendor"
+_BACKEND = Path(__file__).resolve().parents[2] / "backend"
+
+if (_VENDOR / "context_profiles.py").is_file():
+    _ENGINE_DIR = _VENDOR
+elif (_BACKEND / "context_profiles.py").is_file():
+    _ENGINE_DIR = _BACKEND
+else:  # pragma: no cover - defensive
+    raise ImportError(
+        "acm_engine found neither a vendored engine (acm_engine/_vendor/) nor "
+        f"the repo backend at {_BACKEND}. Run `python scripts/sync_engine.py`."
+    )
+
+_engine_str = str(_ENGINE_DIR)
+if _engine_str not in sys.path:
+    sys.path.insert(0, _engine_str)
+
+# Re-export the schema (pure pydantic, zero app coupling).
+from context_profiles import (  # noqa: E402
+    BUILTIN_PRESETS,
+    DEFAULT_PRESET_NAME,
+    PRESET_SUMMARY,
+    Profile,
+    parse_profile,
+)
+
+# Re-export the pure, message-list-level techniques. None of these touch the
+# database, FastAPI, or a LangGraph agent — they take a list of messages and
+# return rewrites.
+from context_editing import (  # noqa: E402
+    _DEFAULT_SUMMARY_SYSTEM as DEFAULT_SUMMARY_SYSTEM,
+    evict_stale_images,
+    sliding_window_trim,
+    summarise_old_messages,
+    trim_tool_results,
+)
+from cache_layout import (  # noqa: E402
+    annotate_cache_breakpoints,
+    read_cache_tokens,
+)
+
+# Task-aware relevance pruning (suggest-only; judge engine ships now, encoder
+# seam ready for Phase 2). Pure, message-list-level like the rest.
+from relevance import (  # noqa: E402
+    Episode,
+    JudgeSuggester,
+    Suggestion,
+    active_task,
+    build_audit_rows,
+    load_audits,
+    load_feedback,
+    record_audit,
+    record_feedback,
+    segment_into_episodes,
+    suggest_removals,
+)
+
+# Local encoder engine (no LLM call). Heavy ML libs load lazily, so importing
+# the class here stays cheap even on a minimal install.
+from relevance_encoder import EncoderSuggester  # noqa: E402
+
+# Where the engine was actually loaded from (vendored copy or repo backend).
+ENGINE_DIR = _ENGINE_DIR
+BACKEND_DIR = _ENGINE_DIR  # back-compat alias
+
+__all__ = [
+    "ENGINE_DIR",
+    "BACKEND_DIR",
+    "BUILTIN_PRESETS",
+    "DEFAULT_PRESET_NAME",
+    "PRESET_SUMMARY",
+    "Profile",
+    "parse_profile",
+    "DEFAULT_SUMMARY_SYSTEM",
+    "trim_tool_results",
+    "summarise_old_messages",
+    "sliding_window_trim",
+    "evict_stale_images",
+    "annotate_cache_breakpoints",
+    "read_cache_tokens",
+    "Episode",
+    "Suggestion",
+    "JudgeSuggester",
+    "segment_into_episodes",
+    "active_task",
+    "suggest_removals",
+    "record_feedback",
+    "load_feedback",
+    "build_audit_rows",
+    "record_audit",
+    "load_audits",
+    "EncoderSuggester",
+]

acm_context_management-0.2.0/acm_engine/_vendor/cache_layout.py

@@ -0,0 +1,218 @@
+"""Provider-agnostic image-recall middleware (cache + eviction at call time).
+
+This is the *common* solution for the image-recall techniques — it works for
+every model the app can route to, because it leans on the one thing all
+caching backends share: **a stable, append-only prefix**.
+
+  * OpenAI / Azure (and OpenAI models via OpenRouter): caching is automatic.
+    Keeping the prefix stable is all that's needed; the cache_control hints
+    we add are simply ignored.
+  * Anthropic / Bedrock-Claude / Gemini (incl. via OpenRouter): caching is
+    explicit. OpenRouter forwards the ``cache_control`` markers we put on
+    content blocks straight through to the upstream provider.
+
+The middleware does both halves of "visual recall", gated by the profile's
+``image_recall.mode``:
+
+  * eviction (``evict`` / ``cache_evict``) — inside ``wrap_model_call`` we
+    drop the pixels of all but the most-recent K image tool-results from the
+    request the model sees, replacing them with their REFERENCES + a digest.
+    Doing it here (not just between turns) means it also fires inside a single
+    agent tool-loop — which is what the single-shot demo needs.
+  * caching (``cache`` / ``cache_evict``) — mark the stable prefix with an
+    ephemeral breakpoint so re-reading the frozen history is cheap/fast.
+    Caching never changes the model's output.
+
+Gotchas baked in:
+  * Breakpoints go on a *text* block, never an image/tool block (Anthropic
+    rejects ``cache_control`` there — langchain issue #34920).
+  * String content is widened to a one-element list so we can hang a marker.
+  * Everything is defensive: an image-recall hiccup must never break a turn.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict, List, Optional
+
+from langchain.agents.middleware import AgentMiddleware
+from langchain_core.messages import AIMessage, BaseMessage, HumanMessage, SystemMessage
+
+log = logging.getLogger("image_recall")
+
+
+# ─── cache-token reader (used by demo + chat to surface cache details) ───
+
+
+def read_cache_tokens(msg: BaseMessage) -> Dict[str, int]:
+    """Pull cache hit/write counts off an AIMessage, provider-agnostic.
+
+    Returns ``{cache_read, cache_write}``. Anthropic/Gemini expose these via
+    ``usage_metadata.input_token_details`` (cache_read / cache_creation);
+    OpenAI exposes a ``cache_read`` only. Falls back to ``response_metadata``
+    when the normalised field is absent. All-zero when nothing cached.
+    """
+    out = {"cache_read": 0, "cache_write": 0}
+    um = getattr(msg, "usage_metadata", None) or {}
+    details = um.get("input_token_details") or {}
+    if isinstance(details, dict):
+        out["cache_read"] = int(details.get("cache_read") or 0)
+        out["cache_write"] = int(
+            details.get("cache_creation") or details.get("cache_write") or 0
+        )
+    if out["cache_read"] == 0 and out["cache_write"] == 0:
+        # OpenAI-style raw usage on response_metadata.
+        rm = getattr(msg, "response_metadata", None) or {}
+        usage = rm.get("usage") or rm.get("token_usage") or {}
+        ptd = (usage.get("prompt_tokens_details") or {}) if isinstance(usage, dict) else {}
+        if isinstance(ptd, dict):
+            out["cache_read"] = int(ptd.get("cached_tokens") or 0)
+    return out
+
+
+# ─── cache breakpoint placement ──────────────────────────────────────────
+
+
+def _last_stable_index(messages: List[BaseMessage]) -> Optional[int]:
+    """Index of the last message in the *settled* prefix (just before the
+    final HumanMessage). The newest turn stays dynamic / reprocessed fresh."""
+    if len(messages) < 2:
+        return None
+    last_human = None
+    for i in range(len(messages) - 1, -1, -1):
+        if isinstance(messages[i], HumanMessage):
+            last_human = i
+            break
+    boundary = (last_human - 1) if last_human is not None else (len(messages) - 1)
+    return boundary if boundary >= 0 else None
+
+
+def _mark_block(msg: BaseMessage, ttl: str) -> bool:
+    """Attach an ephemeral cache_control marker to a *text* block of ``msg``.
+    Skips image / non-text blocks. Returns True if a marker was placed."""
+    cc: Dict[str, Any] = {"type": "ephemeral"}
+    if ttl == "1h":
+        cc["ttl"] = "1h"
+    content = getattr(msg, "content", None)
+    if isinstance(content, str):
+        if not content.strip():
+            return False
+        msg.content = [{"type": "text", "text": content, "cache_control": cc}]
+        return True
+    if isinstance(content, list):
+        for block in reversed(content):
+            if isinstance(block, dict) and block.get("type") == "text":
+                block["cache_control"] = cc
+                return True
+    return False
+
+
+def annotate_cache_breakpoints(
+    messages: List[BaseMessage],
+    *,
+    system: Optional[BaseMessage] = None,
+    ttl: str = "5m",
+) -> int:
+    """Place ephemeral breakpoints on the stable prefix (system + last settled
+    message). Mutates in place; returns how many breakpoints were set."""
+    placed = 0
+    if isinstance(system, SystemMessage) and _mark_block(system, ttl):
+        placed += 1
+    idx = _last_stable_index(messages)
+    if idx is not None:
+        target = messages[idx]
+        if target.__class__.__name__ == "ToolMessage":
+            # Don't mark a bare tool block; walk back to an AI/System text block.
+            for j in range(idx, -1, -1):
+                if isinstance(messages[j], (AIMessage, SystemMessage)):
+                    target = messages[j]
+                    break
+        if _mark_block(target, ttl):
+            placed += 1
+    return placed
+
+
+# ─── the middleware ──────────────────────────────────────────────────────
+
+
+class ImageRecallMiddleware(AgentMiddleware):
+    """Applies the selected image-recall technique on every model call.
+
+    ``mode`` ∈ {off, cache, evict, cache_evict}. Provider-agnostic: caching is
+    a no-op effect for auto-caching backends and active for explicit ones.
+    Attach only when ``mode != off``.
+    """
+
+    def __init__(
+        self,
+        *,
+        mode: str = "off",
+        keep_recent_images: int = 3,
+        ttl: str = "5m",
+    ) -> None:
+        super().__init__()
+        self.mode = mode if mode in {"off", "cache", "evict", "cache_evict"} else "off"
+        self.keep_recent_images = max(1, int(keep_recent_images or 3))
+        self.ttl = ttl if ttl in {"5m", "1h"} else "5m"
+
+    @property
+    def caching_enabled(self) -> bool:
+        return self.mode in {"cache", "cache_evict"}
+
+    @property
+    def eviction_enabled(self) -> bool:
+        return self.mode in {"evict", "cache_evict"}
+
+    def _apply(self, request) -> None:
+        """Mutate request.messages in place: evict stale images, then mark
+        cache breakpoints. Order matters — eviction first so the breakpoint
+        lands on the de-imaged prefix."""
+        msgs = getattr(request, "messages", None)
+        if not msgs:
+            return
+        if self.eviction_enabled:
+            # Lazy import avoids a context_editing <-> cache_layout cycle.
+            from context_editing import evict_stale_images
+
+            replacements, info = evict_stale_images(
+                msgs, keep_recent_images=self.keep_recent_images
+            )
+            if replacements:
+                by_id = {getattr(r, "id", None): r for r in replacements}
+                request.messages = [
+                    by_id.get(getattr(m, "id", None), m) for m in msgs
+                ]
+                msgs = request.messages
+                log.info(
+                    "[image_recall] evicted %d stale image(s), kept %d as pixels, freed ~%d tokens",
+                    info["evicted"], info["kept_recent"], info["freed_tokens"],
+                )
+        if self.caching_enabled:
+            placed = annotate_cache_breakpoints(
+                msgs,
+                system=getattr(request, "system_message", None),
+                ttl=self.ttl,
+            )
+            if placed:
+                log.info(
+                    "[image_recall] placed %d cache breakpoint(s) (ttl=%s) on the stable prefix",
+                    placed, self.ttl,
+                )
+
+    def wrap_model_call(self, request, handler):  # type: ignore[override]
+        try:
+            self._apply(request)
+        except Exception as e:  # never break the turn over image-recall
+            log.warning("[image_recall] apply failed: %r", e)
+        return handler(request)
+
+    async def awrap_model_call(self, request, handler):  # type: ignore[override]
+        try:
+            self._apply(request)
+        except Exception as e:
+            log.warning("[image_recall] apply failed: %r", e)
+        return await handler(request)
+
+
+# Back-compat alias (earlier name during development).
+CachePrefixMiddleware = ImageRecallMiddleware