lightfoot 1.0.0__py3-none-any.whl

lightfoot/__init__.py

@@ -0,0 +1,3 @@
+"""A local, cache-aware token-saving proxy for coding agents."""
+
+__version__ = "1.0.0"

lightfoot/__main__.py

@@ -0,0 +1,7 @@
+"""`python -m lightfoot`: the same as the `lightfoot` command."""
+
+import sys
+
+from .cli import main
+
+sys.exit(main())

lightfoot/adapters/__init__.py

@@ -0,0 +1,49 @@
+"""Protocol adapters, chosen by request path."""
+
+from __future__ import annotations
+
+import re
+
+from .anthropic import AnthropicAdapter
+from .base import Adapter, Index, Result, ToolCall, apply_changes, count_cache_markers
+from .chat import ChatAdapter
+from .gemini import GeminiAdapter
+from .responses import ResponsesAdapter
+
+ANTHROPIC = AnthropicAdapter()
+RESPONSES = ResponsesAdapter()
+GEMINI = GeminiAdapter()
+CHAT = ChatAdapter()
+
+GEMINI_PATH_RE = re.compile(r"(?:^|/)models/[^/]+:(?:stream)?generateContent$", re.I)
+
+
+def for_path(method: str, path: str) -> Adapter | None:
+    """The adapter that rewrites this request, or None for pure passthrough."""
+    if method != "POST":
+        return None
+    path = path.rstrip("/")
+    if path.endswith("v1/messages"):
+        return ANTHROPIC
+    if path.endswith("/responses") or path == "responses":
+        return RESPONSES
+    if GEMINI_PATH_RE.search(path):
+        return GEMINI
+    if path.endswith("chat/completions"):
+        return CHAT
+    return None
+
+
+__all__ = [
+    "ANTHROPIC",
+    "CHAT",
+    "GEMINI",
+    "RESPONSES",
+    "Adapter",
+    "Index",
+    "Result",
+    "ToolCall",
+    "apply_changes",
+    "count_cache_markers",
+    "for_path",
+]

lightfoot/adapters/anthropic.py

@@ -0,0 +1,259 @@
+"""Anthropic Messages API (POST /v1/messages): Claude Code and Claude Agent SDK apps."""
+
+from __future__ import annotations
+
+import hashlib
+
+from ..images import image_tokens, is_base64_image
+from ..text import tokens
+from ..usage import AnthropicUsage
+from .base import Adapter, Index, Result, ToolCall, canonical, encode
+
+THINKING_TYPES = {"thinking", "redacted_thinking"}
+
+
+def plain_text(content) -> str:
+    """The text of a string or a list of content blocks; non-text blocks are skipped."""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        return "".join(
+            b.get("text", "")
+            for b in content
+            if isinstance(b, dict) and b.get("type") == "text" and isinstance(b.get("text"), str)
+        )
+    return ""
+
+
+class AnthropicAdapter(Adapter):
+    """Anthropic Messages: the only adapter verified for history edits (epochs, prunes, drop_block)."""
+
+    name = "anthropic"
+    units_key = "messages"
+    epochs_supported = True
+    supports_prune = True
+    supports_drop_block = True
+
+    def index(self, body, profile):
+        """Index an Anthropic Messages request: tool_result blocks are the rewritable content,
+        thinking and redacted_thinking blocks mark the reasoning units.
+        """
+        msgs = body["messages"]
+        calls: dict[str, ToolCall] = {}
+        pending = []
+        unit_turn: list[int] = []
+        reasoning: set[int] = set()
+        turn = 0
+        for mi, message in enumerate(msgs):
+            role = message.get("role") if isinstance(message, dict) else None
+            if role == "user":
+                turn += 1
+            unit_turn.append(turn)
+            content = message.get("content") if isinstance(message, dict) else None
+            if not isinstance(content, list):
+                continue
+            for bi, block in enumerate(content):
+                if not isinstance(block, dict):
+                    continue
+                kind = block.get("type")
+                if role == "assistant" and kind in THINKING_TYPES:
+                    reasoning.add(mi)
+                if kind == "tool_use" and role == "assistant" and isinstance(block.get("id"), str):
+                    inp = block.get("input") if isinstance(block.get("input"), dict) else {}
+                    name = str(block.get("name") or "")
+                    calls[block["id"]] = ToolCall(name, inp, profile.kind(name, inp), mi)
+                elif kind == "tool_result" and role == "user":
+                    pending.append((mi, bi, block, turn))
+
+        results = []
+        for mi, bi, block, t in pending:
+            tid = block.get("tool_use_id") if isinstance(block.get("tool_use_id"), str) else ""
+            call = calls.get(tid)
+            shape, text = self.extract(block)
+            is_error = bool(block.get("is_error"))
+            media = [c for c in block["content"] if is_base64_image(c)] if shape == "image" else []
+            results.append(
+                Result(
+                    unit=mi,
+                    path=("messages", mi, "content", bi, "content"),
+                    tid=tid,
+                    container=block,
+                    name=call.name if call else "",
+                    inp=call.inp if call else {},
+                    kind=call.kind if call else "other",
+                    turn=t,
+                    shape=shape,
+                    orig_text=text,
+                    is_error=is_error,
+                    media=media,
+                )
+            )
+
+        # Trailing system messages (Claude Code 2.1.310+) don't end the user's turn: skip them.
+        last = len(msgs) - 1
+        while last >= 0 and isinstance(msgs[last], dict) and msgs[last].get("role") == "system":
+            last -= 1
+        ingest_from = (
+            last if last >= 0 and isinstance(msgs[last], dict) and msgs[last].get("role") == "user" else len(msgs)
+        )
+        model_from = ingest_from - 1
+        while model_from >= 0 and isinstance(msgs[model_from], dict) and msgs[model_from].get("role") == "system":
+            model_from -= 1
+        if model_from < 0:
+            model_from = len(msgs)
+        return Index(msgs, results, calls, unit_turn, turn, ingest_from, model_from, reasoning)
+
+    def extract(self, container):
+        """Shape and text of a tool_result's content, or (None, None) when it can't be rewritten.
+
+        "str" and "list" are plain text. "image" is text blocks plus at least one inline image;
+        only the images rule rewrites it. Documents, URL images, extra block fields or more than
+        one cache marker make the content non-rewritable.
+        """
+        content = container.get("content")
+        if isinstance(content, str):
+            return ("str", content) if content else (None, None)
+        if isinstance(content, list) and content:
+            texts, markers, has_image = [], 0, False
+            for inner in content:
+                if is_base64_image(inner) and not set(inner) - {"type", "source", "cache_control"}:
+                    has_image = True
+                elif (
+                    isinstance(inner, dict)
+                    and inner.get("type") == "text"
+                    and isinstance(inner.get("text"), str)
+                    and not set(inner) - {"type", "text", "cache_control"}
+                ):
+                    texts.append(inner["text"])
+                else:
+                    return None, None
+                markers += "cache_control" in inner
+            if markers > 1:
+                return None, None
+            return ("image" if has_image else "list"), "\n".join(texts)
+        return None, None
+
+    def content_value(self, container, shape, text):
+        """A string for a "str" result; otherwise one text block that keeps the client's cache marker."""
+        if shape == "str":
+            return text
+        inner = {"type": "text", "text": text}
+        for old in container.get("content") or []:
+            if isinstance(old, dict) and "cache_control" in old:
+                inner["cache_control"] = old["cache_control"]  # markers follow the client's placement
+        return [inner]
+
+    def content_text(self, value):
+        """Text of a string or of a list of text blocks."""
+        if isinstance(value, str):
+            return value
+        if isinstance(value, list) and all(isinstance(b, dict) and b.get("type") == "text" for b in value):
+            return "\n".join(str(b.get("text", "")) for b in value)
+        return None
+
+    def block_tokens(self, block: dict) -> int:
+        """Tokens of one content block, with images at their real cost rather than their base64 length."""
+        kind = block.get("type")
+        if kind == "text":
+            return tokens(str(block.get("text", "")))
+        if kind in THINKING_TYPES:
+            return tokens(str(block.get("thinking", "")))
+        if kind == "image":
+            return image_tokens(block)
+        if kind == "tool_result":
+            content = block.get("content")
+            if isinstance(content, list):
+                return sum(self.block_tokens(c) for c in content if isinstance(c, dict))
+            return tokens(content) if isinstance(content, str) else 0
+        return tokens(canonical(block))
+
+    def unit_text(self, ui, unit, current):
+        """Text, tool inputs and tool results of one message, with rewritten results taken from `current`."""
+        content = unit.get("content")
+        if isinstance(content, str):
+            return content
+        parts = []
+        for bi, block in enumerate(content or []):
+            if not isinstance(block, dict):
+                continue
+            kind = block.get("type")
+            if kind == "text":
+                parts.append(str(block.get("text", "")))
+            elif kind == "tool_use":
+                parts.append(canonical(block.get("input")))
+            elif kind == "tool_result":
+                path = ("messages", ui, "content", bi, "content")
+                parts.append(current.get(path, plain_text(block.get("content"))) or "")
+        return "\n".join(parts)
+
+    def unit_tokens(self, ui, unit, current):
+        """Tokens of one message, with rewritten results taken from `current`."""
+        content = unit.get("content")
+        if isinstance(content, str):
+            return tokens(content)
+        total = 0
+        for bi, block in enumerate(content or []):
+            if not isinstance(block, dict):
+                continue
+            path = ("messages", ui, "content", bi, "content")
+            if path in current:
+                total += tokens(current[path] or "")
+            else:
+                total += self.block_tokens(block)
+        return total
+
+    def session_key(self, body):
+        """System prompt + first user message: stable for a conversation, distinct per subagent."""
+        system = body.get("system")
+        system_text = system if isinstance(system, str) else plain_text(system)
+        first = next((m for m in body.get("messages", []) if isinstance(m, dict) and m.get("role") == "user"), None)
+        first_text = plain_text(first.get("content")) if first else ""
+        return hashlib.sha256(encode(system_text + "\x00" + first_text)).hexdigest()[:16]
+
+    def cache_ttl(self, body):
+        """300 for the default cache, 3600 if the client marks blocks with a 1-hour TTL."""
+
+        def scan(blocks) -> bool:
+            if isinstance(blocks, list):
+                for b in blocks:
+                    if isinstance(b, dict):
+                        cc = b.get("cache_control")
+                        if isinstance(cc, dict) and cc.get("ttl") == "1h":
+                            return True
+                        if scan(b.get("content")):
+                            return True
+            return False
+
+        top = body.get("cache_control")
+        if isinstance(top, dict) and top.get("ttl") == "1h":
+            return 3600
+        candidates = [body.get("system"), body.get("tools")]
+        candidates += [m.get("content") for m in body.get("messages", [])[-3:] if isinstance(m, dict)]
+        return 3600 if any(scan(c) for c in candidates) else 300
+
+    def with_drop_block(self, body):
+        """Set `thinking.block_binding.prefix_mismatch_behavior` to `drop_block`.
+
+        The client's other thinking settings are kept.
+        """
+        thinking = dict(body["thinking"])
+        binding = dict(thinking.get("block_binding") or {})
+        binding["prefix_mismatch_behavior"] = "drop_block"
+        thinking["block_binding"] = binding
+        out = dict(body)
+        out["thinking"] = thinking
+        return out
+
+    def usage_parser(self, content_type, request_body):
+        """Usage from `message_start` and `message_delta`, or from a non-streamed body."""
+        return AnthropicUsage(content_type)
+
+    def prefix(self, body):
+        """The system prompt's texts and each tool definition by name."""
+        system = body.get("system")
+        if isinstance(system, str):
+            texts = [system]
+        else:
+            texts = [str(b.get("text", "")) for b in system or [] if isinstance(b, dict)]
+        tools = [(str(t.get("name", "")), t) for t in body.get("tools") or [] if isinstance(t, dict)]
+        return texts, tools

lightfoot/adapters/base.py

@@ -0,0 +1,224 @@
+"""Protocol-neutral view of a request, shared by every adapter.
+
+An adapter turns a provider's request body into an `Index`: the conversation's units
+(Anthropic messages, OpenAI input items), the tool calls, and every tool output with
+the JSON path of its content. The core engine only ever replaces content at those
+paths, so one generic `apply_changes` and one generic validator serve all protocols.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+
+from ..images import image_tokens
+from ..text import tokens
+
+Path = tuple  # JSON path into the request body, e.g. ("messages", 4, "content", 0, "content")
+
+
+def encode(text: str) -> bytes:
+    """UTF-8 bytes of `text`, keeping lone surrogates that some clients send."""
+    return text.encode("utf-8", "surrogatepass")
+
+
+def canonical(value) -> str:
+    """Deterministic JSON for hashing and comparison: sorted keys, ASCII only, no spaces."""
+    return json.dumps(value, sort_keys=True, ensure_ascii=True, separators=(",", ":"))
+
+
+def content_hash(shape: str, is_error: bool, text: str) -> str:
+    """Hash of what a tool output says, ignoring cache_control placement (markers move between turns)."""
+    return hashlib.sha256(f"{shape}|{int(is_error)}|".encode() + encode(text)).hexdigest()
+
+
+@dataclass
+class ToolCall:
+    """A tool call the model made, by id; results look up their call to learn name, input and kind."""
+
+    name: str
+    inp: dict
+    kind: str
+    unit: int
+
+
+@dataclass
+class Result:
+    """One tool output in the request: the only kind of content a rule may rewrite.
+
+    `orig_text` is what the client sent; `text` is set when a stored or new rewrite applies.
+    Rewrites are keyed by `tid` and checked against `orig_hash`, so a replay never lands on
+    output that has changed since it was frozen.
+    """
+
+    unit: int
+    path: Path  # where the content lives
+    tid: str  # stable id used for frozen replay (tool_use_id / call_id)
+    container: dict  # the dict whose content field is replaced
+    name: str
+    inp: dict
+    kind: str  # read | search | shell | edit | subagent | graph_query | other
+    turn: int
+    shape: str | None  # "str" | "list" | None (not rewritable)
+    orig_text: str | None
+    is_error: bool
+    text: str | None = None  # current text when a rewrite applies
+    rule: str | None = None
+    note_path: str | None = None
+    source: str | None = None  # "stored" | "new"
+    media: list = field(default_factory=list)  # inline image blocks (shape "image" only)
+    _hash: str | None = field(default=None, repr=False)
+
+    @property
+    def orig_hash(self) -> str | None:
+        """Content hash, computed only when needed (replay checks, new rewrites, repeat detection)."""
+        if self._hash is None and self.shape is not None:
+            text = self.orig_text or ""
+            if self.media:
+                # Screenshots often carry no text at all, so the image data must be part of the hash.
+                text += "\x00" + "".join(hashlib.sha256(encode(b["source"]["data"])).hexdigest() for b in self.media)
+            self._hash = content_hash(self.shape, self.is_error, text)
+        return self._hash
+
+    @property
+    def current(self) -> str | None:
+        """The text this result will carry: the rewrite if one applies, else the original."""
+        return self.text if self.text is not None else self.orig_text
+
+    @property
+    def orig_tokens(self) -> int:
+        """Tokens of the original content, images included at their real cost."""
+        return tokens(self.orig_text or "") + sum(image_tokens(b) for b in self.media)
+
+    @property
+    def current_tokens(self) -> int:
+        """Tokens of `current`, images included at their real cost while unrewritten."""
+        return tokens(self.text) if self.text is not None else self.orig_tokens
+
+    @property
+    def rewritable(self) -> bool:
+        """Whether any rule may touch this result: a known shape, not an error, and a stable id."""
+        return self.shape is not None and not self.is_error and bool(self.tid)
+
+
+@dataclass
+class Index:
+    """Everything the planner needs to know about a request, independent of its wire format.
+
+    `ingest_from` splits history (seen by the model, so editing it is a history edit) from
+    new content (free to rewrite). `reasoning_units` lets the planner tell whether a history
+    edit would land before a thinking block, whose signature binds everything before it.
+    """
+
+    units: list
+    results: list[Result]
+    calls: dict[str, ToolCall]
+    unit_turn: list[int]
+    turns: int
+    ingest_from: int  # first unit the model has not seen yet
+    model_from: int  # first unit of the newest model turn (for signals)
+    reasoning_units: set[int] = field(default_factory=set)
+    pruned_before: int = 0  # units before this are replaced by a stored prune summary
+
+    def reasoning_after(self, unit: int) -> bool:
+        """Whether a thinking or reasoning unit comes after `unit`, so editing `unit` would break its signature."""
+        return any(u > unit for u in self.reasoning_units)
+
+
+def apply_changes(body: dict, changes: dict[Path, object]) -> dict:
+    """Copy of `body` with each path replaced; everything not on a changed path is shared."""
+    out = dict(body)
+    copied: dict[tuple, object] = {(): out}
+    for path, value in changes.items():
+        node = out
+        for depth in range(len(path) - 1):
+            prefix = path[: depth + 1]
+            if prefix not in copied:
+                child = node[path[depth]]
+                child = list(child) if isinstance(child, list) else dict(child)
+                node[path[depth]] = child
+                copied[prefix] = child
+            node = copied[prefix]
+        node[path[-1]] = value
+    return out
+
+
+def count_cache_markers(value) -> int:
+    """How many `cache_control` markers `value` holds, at any depth.
+
+    The validator requires the same count after a rewrite.
+    """
+    if isinstance(value, dict):
+        return ("cache_control" in value) + sum(
+            count_cache_markers(v) for k, v in value.items() if k != "cache_control"
+        )
+    if isinstance(value, list):
+        return sum(count_cache_markers(v) for v in value)
+    return 0
+
+
+class Adapter:
+    """Interface every protocol adapter implements."""
+
+    name = "base"
+    units_key = ""
+    epochs_supported = False  # history edits verified safe for this provider
+    supports_prune = False  # old-turn pruning (a history edit, so it needs the same verification)
+    supports_drop_block = False
+    experimental = False
+
+    def accepts(self, body) -> bool:
+        """Whether this adapter can index `body`: a dict whose `units_key` holds a list."""
+        return isinstance(body, dict) and isinstance(body.get(self.units_key), list)
+
+    def index(self, body: dict, profile) -> Index:
+        """Build the protocol-neutral `Index` of a request, using `profile` to give each tool call its kind."""
+        raise NotImplementedError
+
+    def extract(self, container: dict) -> tuple[str | None, str | None]:
+        """Shape and plain text of a tool output's content, or (None, None) when it can't be rewritten."""
+        raise NotImplementedError
+
+    def content_value(self, container: dict, shape: str, text: str):
+        """The value to store in `container`'s content field for rewritten `text`, in the original's `shape`."""
+        raise NotImplementedError
+
+    def content_text(self, value) -> str | None:
+        """Plain text of a stored content value, or None when it isn't plain text."""
+        raise NotImplementedError
+
+    def unit_text(self, ui: int, unit: dict, current: dict[Path, str]) -> str:
+        """Plain text of unit `ui` for "referenced since" checks; `current` maps result path -> text."""
+        raise NotImplementedError
+
+    def unit_tokens(self, ui: int, unit: dict, current: dict[Path, str]) -> int:
+        """Tokens of unit `ui`, counting rewritten results from `current` (result path -> text)."""
+        raise NotImplementedError
+
+    def session_key(self, body: dict) -> str:
+        """A stable id for the conversation `body` belongs to, the same on every one of its turns."""
+        raise NotImplementedError
+
+    def cache_ttl(self, body: dict) -> int:
+        """Seconds the provider keeps this request's prompt cache; 300 unless the protocol says otherwise."""
+        return 300
+
+    def model(self, body: dict) -> str | None:
+        """The model named in the request body, if any."""
+        return body.get("model") if isinstance(body.get("model"), str) else None
+
+    def with_drop_block(self, body: dict) -> dict:
+        """`body` with the provider told to drop thinking that no longer matches its prefix.
+
+        A no-op for providers without that option.
+        """
+        return body
+
+    def usage_parser(self, content_type: str | None, request_body: dict | None):
+        """A parser that reads token usage from this protocol's response, streamed or not."""
+        raise NotImplementedError
+
+    def prefix(self, body: dict) -> tuple[list[str], list[tuple[str, object]]]:
+        """The fixed prefix every request of a session repeats: system texts, and (name, definition) per tool."""
+        return [], []