pcode 0.1.0__py3-none-any.whl

pcode/delta.py

@@ -0,0 +1,295 @@
+"""Diffs rendered by delta (https://dandavison.github.io/delta/) when it is installed.
+
+delta never reads the user's git config (`--no-gitconfig`, which also ignores
+`--config`) or its own `DELTA_*`/`BAT_*` environment: `delta_args` is the one
+place to customize it, so pcode's diffs look the same whatever `git diff` is set
+up to do. pcode sets width, dark or light, no pager or headers, layout, and
+syntax colors on deletions. It leaves out defaults the user's own arguments
+already pass: delta rejects a flag given twice. Anything that goes wrong (delta
+missing, unknown arguments, a timeout) returns None, and the caller falls back
+to its own Rich rendering.
+"""
+
+import os
+import secrets
+import shlex
+import shutil
+import subprocess
+import threading
+from collections import OrderedDict
+from dataclasses import dataclass
+
+from rich.cells import chop_cells
+from rich.text import Text
+
+LAYOUTS = ("auto", "unified", "side-by-side")
+WIDTH_FLAGS = {"-w", "--width"}
+SIDE_BY_SIDE_FLAGS = {"-s", "--side-by-side"}
+LINE_NUMBER_FLAGS = {"-n", "--line-numbers"}
+# `auto` switches to side-by-side at this width: each half then keeps about 90
+# columns, enough for most code lines beside their line numbers.
+SIDE_BY_SIDE_WIDTH = 180
+TIMEOUT = 2.0
+# A batch gets a little longer per patch, up to this.
+MAX_TIMEOUT = 5.0
+# Patches per delta run, so a batch fits within MAX_TIMEOUT.
+BATCH = 60
+# delta extends a background to the edge with "erase to end of line", which
+# neither Rich nor prompt_toolkit keeps; it is replaced with padding instead.
+ERASE_LINE = "\x1b[0K"
+_MARK = "\ue000"
+
+
+@dataclass(frozen=True)
+class Delta:
+    executable: str
+    args: tuple[str, ...] = ()
+    layout: str = "unified"
+    light: bool = False
+
+    def side_by_side(self, width: int) -> bool:
+        if self.given() & SIDE_BY_SIDE_FLAGS:
+            return True
+        if self.layout == "auto":
+            return width >= SIDE_BY_SIDE_WIDTH
+        return self.layout == "side-by-side"
+
+    def given(self) -> set[str]:
+        """The flags the user's own arguments set."""
+        return {arg.split("=", 1)[0] for arg in self.args if arg.startswith("-")}
+
+    def command(self, width: int) -> list[str]:
+        given = self.given()
+        defaults = [
+            ({"--paging"}, "--paging=never"),
+            (WIDTH_FLAGS, f"--width={width}"),
+            # Match additions' syntax colors without changing delta's backgrounds.
+            ({"--minus-style"}, "--minus-style=syntax auto"),
+            ({"--minus-emph-style"}, "--minus-emph-style=syntax auto"),
+            ({"--dark", "--light"}, "--light" if self.light else "--dark"),
+            # The block heading already names the file.
+            ({"--file-style"}, "--file-style=omit"),
+            # A boxed `line: function` heading that often holds only a number.
+            ({"--hunk-header-style"}, "--hunk-header-style=omit"),
+        ]
+        if self.side_by_side(width):
+            defaults.append((SIDE_BY_SIDE_FLAGS, "--side-by-side"))
+        added = [flag for names, flag in defaults if not names & given]
+        isolated = [] if "--no-gitconfig" in given else ["--no-gitconfig"]
+        return [self.executable, *isolated, *added, *self.args]
+
+    def render(self, patch: str, width: int, *, cache: bool = True) -> list[Text] | None:
+        """One styled Rich row per output row, or None if delta failed.
+
+        Safe to call off the event loop. Without `cache`, the output is not
+        kept, so the live preview's many short-lived bodies do not push the
+        settled blocks' renderings out.
+        """
+        command = tuple(self.command(max(1, width)))
+        key = (command, patch)
+        with _lock:
+            cached = key in _cache
+            if cached:
+                _cache.move_to_end(key)
+                output = _cache[key]
+        if not cached:
+            output = _run(command, patch)
+            if cache:
+                _remember(key, output)
+        groups = self._groups(command, width, output)
+        return None if groups is None else [row for group in groups for row in group]
+
+    def render_all(self, patches: list[str], width: int) -> list[list[list[Text]] | None]:
+        """Each patch through one delta run, as one group of rows per output line.
+
+        Unlike `render`, the results come back rather than through the shared
+        cache, so a review with more hunks than the cache holds is not evicted
+        while it is laid out. A line delta folds keeps its rows together, so a
+        caller can match output lines to patch lines. None marks a patch delta
+        failed on.
+        """
+        command = tuple(self.command(max(1, width)))
+        outputs = self._outputs(command, patches)
+        return [self._groups(command, width, outputs.get(patch)) for patch in patches]
+
+    def prefetch(self, patches: list[str], width: int) -> None:
+        """Render many patches through one delta process, ready for `render`."""
+        self._outputs(tuple(self.command(max(1, width))), patches)
+
+    def _outputs(self, command: tuple[str, ...], patches: list[str]) -> dict[str, str | None]:
+        """delta's raw output for each patch, running only those not cached.
+
+        Starting delta costs tens of milliseconds, and a scrollback rebuild
+        renders every edit block at once. The patches go in one input,
+        separated by a marker line delta passes through untouched, since only
+        `+`, `-`, space and backslash lines continue a hunk. A big set goes in
+        batches, each within one run's timeout. If a batch's output does not
+        split back into one piece per patch, its patches are left unrendered
+        (None, and not cached) rather than each started alone: a review can hold
+        hundreds. If delta fails outright, every patch is recorded as failed,
+        so the blocks fall back to Rich at once instead of each waiting on its
+        own failing run.
+        """
+        outputs: dict[str, str | None] = {}
+        with _lock:
+            for patch in dict.fromkeys(patches):
+                if (command, patch) in _cache:
+                    outputs[patch] = _cache[(command, patch)]
+        missing = [patch for patch in dict.fromkeys(patches) if patch not in outputs]
+        if len(missing) == 1:
+            outputs[missing[0]] = _remember((command, missing[0]), _run(command, missing[0]))
+            return outputs
+        for start in range(0, len(missing), BATCH):
+            batch = missing[start : start + BATCH]
+            marker = f"pcode-delta-{secrets.token_hex(8)}"
+            output = _run(command, f"\n{marker}\n".join(batch), len(batch))
+            pieces = None if output is None else output.split(f"{marker}\n")
+            if pieces is not None and len(pieces) != len(batch):
+                outputs.update(dict.fromkeys(batch))
+                continue
+            for patch, piece in zip(batch, pieces or [None] * len(batch), strict=True):
+                outputs[patch] = _remember(
+                    (command, patch), piece if piece and piece.strip() else None
+                )
+        return outputs
+
+    def _groups(
+        self, command: tuple[str, ...], width: int, output: str | None
+    ) -> list[list[Text]] | None:
+        if output is None:
+            return None
+        lines = output.splitlines()
+        # With the file section omitted, delta still opens with its blank line.
+        # Only that one: a hunk's first context line can be blank too.
+        if lines and not lines[0].strip():
+            lines.pop(0)
+        # Padding to pcode's width would wrap every row of a wider user width.
+        pad = 0 if self.given() & WIDTH_FLAGS else width
+        gutter = bool(set(command) & LINE_NUMBER_FLAGS)
+        return [_rows(line, pad, gutter) for line in lines]
+
+
+def from_preferences(preferences: dict[str, str], *, light: bool = False) -> Delta | None:
+    """The configured delta, or None to render diffs with Rich."""
+    if preferences.get("diff_renderer", "delta") != "delta":
+        return None
+    executable = find_delta()
+    if executable is None:
+        return None
+    try:
+        args = tuple(shlex.split(preferences.get("delta_args", "")))
+    except ValueError:
+        args = ()
+    layout = preferences.get("diff_layout", "unified")
+    return Delta(executable, args, layout if layout in LAYOUTS else "unified", light)
+
+
+def find_delta() -> str | None:
+    return shutil.which("delta")
+
+
+# delta's output by (command, patch): a rebuild at the same width and palette
+# reuses it rather than starting delta again.
+_cache: OrderedDict[tuple[tuple[str, ...], str], str | None] = OrderedDict()
+CACHE_SIZE = 256
+
+
+# The live edit preview renders from a worker thread.
+_lock = threading.Lock()
+
+
+def _remember(key: tuple[tuple[str, ...], str], output: str | None) -> str | None:
+    with _lock:
+        _cache[key] = output
+        _cache.move_to_end(key)
+        while len(_cache) > CACHE_SIZE:
+            _cache.popitem(last=False)
+    return output
+
+
+def preview_patch(path: str, body: str) -> str:
+    """A unified diff of a streaming edit preview's `-`/`+` lines.
+
+    The preview has no line numbers, so the hunk is numbered from 1; its
+    header is never drawn. The path's extension picks the
+    syntax highlighting. A line the preview's tail clip cut short of its
+    prefix is dropped.
+    """
+    lines = [line for line in body.split("\n") if line[:1] in ("-", "+")]
+    removed = sum(line.startswith("-") for line in lines)
+    header = [f"--- a/{path}", f"+++ b/{path}", f"@@ -1,{removed} +1,{len(lines) - removed} @@"]
+    return "\n".join(header + lines)
+
+
+def _run(command: tuple[str, ...], patch: str, count: int = 1) -> str | None:
+    try:
+        done = subprocess.run(
+            command,
+            input=patch + "\n",
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=min(TIMEOUT + 0.05 * count, MAX_TIMEOUT),
+            # A user's --paging=always would start a pager holding the pipes.
+            env=_environment(),
+            # No controlling terminal: delta must never query or write the
+            # terminal pcode is drawing on.
+            start_new_session=True,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if done.returncode != 0 or not done.stdout.strip():
+        return None
+    return done.stdout
+
+
+def _environment() -> dict[str, str]:
+    # DELTA_FEATURES, BAT_THEME and the like configure delta behind the
+    # user's arguments. A pager could hold the pipes open, so it is `cat`.
+    env = {
+        key: value for key, value in os.environ.items() if not key.startswith(("DELTA_", "BAT_"))
+    }
+    return {**env, "DELTA_PAGER": "cat"}
+
+
+def _rows(raw: str, width: int, gutter: bool) -> list[Text]:
+    """Parse one ANSI line into rows of at most `width` cells (0 for any width).
+
+    The unified layout never wraps, and a long row left to the terminal would
+    restart under the line numbers, so it is folded here, each continuation
+    indented past the `gutter` when `--line-numbers` draws one. Where delta erased to the
+    end of the line, every row is padded in that background.
+    """
+    if ERASE_LINE not in raw:
+        text, style = Text.from_ansi(raw), None
+    else:
+        text = Text.from_ansi(raw.split(ERASE_LINE, 1)[0] + _MARK)
+        style = next(
+            (span.style for span in reversed(text.spans) if span.start <= len(text) - 1 < span.end),
+            "",
+        )
+        text.right_crop(1)
+    rows = _fold(text, width, gutter) if width else [text]
+    if style is not None:
+        for row in rows:
+            if (pad := width - row.cell_len) > 0:
+                row.append(" " * pad, style)
+    return rows
+
+
+def _fold(text: Text, width: int, gutter: bool) -> list[Text]:
+    if text.cell_len <= width:
+        return [text]
+    # The line-number gutter ends at its first bar, like ` 24 ⋮ 25 │`.
+    bar = text.plain.find("│") if gutter else -1
+    indent = bar + 1 if 0 < bar < width // 2 else 0
+    prefix = Text(" " * (indent - 1)) + text[bar:indent] if indent else Text()
+    # chop_cells measures whole grapheme clusters, so an emoji never splits.
+    first = chop_cells(text.plain, width)[0]
+    start = len(first)
+    rows = [text[:start]]
+    for piece in chop_cells(text.plain[start:], width - indent):
+        rows.append(prefix + text[start : start + len(piece)])
+        start += len(piece)
+    return rows

pcode/diagnostics.py

@@ -0,0 +1,226 @@
+"""Useful provider errors without HTTP headers or credential values."""
+
+import os
+import re
+import sysconfig
+import traceback
+from importlib.metadata import version
+from pathlib import Path
+from urllib.parse import urlsplit, urlunsplit
+
+RESTART = "Restart pcode to load it; /resume picks this conversation back up."
+
+
+def stale_install() -> str | None:
+    """Why this process's code may no longer match what is on disk.
+
+    pcode imports much of itself lazily, and the global install is editable, so
+    a long-lived session that outlives a merge mixes old modules with new ones
+    (a new module reading a setting the old one never defined), and one that
+    outlives a reinstall on another Python finds its site-packages deleted.
+    Both surface as unrelated-looking errors far from the cause.
+    """
+    import pcode
+
+    if not Path(sysconfig.get_paths()["purelib"]).is_dir():
+        return f"pcode was reinstalled since this session started. {RESTART}"
+    try:
+        changed = any(
+            path.stat().st_mtime > pcode.STARTED
+            for path in Path(pcode.__file__).parent.rglob("*.py")
+        )
+    except OSError:
+        changed = True  # A file vanished mid-scan: the source is changing.
+    return f"pcode's source changed since this session started. {RESTART}" if changed else None
+
+
+_TOKEN = re.compile(
+    r"\b(?:sk-[A-Za-z0-9_-]{12,}|gh[pousr]_[A-Za-z0-9]{12,}|"
+    r"eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+)\b"
+)
+_ASSIGNMENT = re.compile(
+    r"(?i)((?:api[_-]?key|access[_-]?token|refresh[_-]?token|id[_-]?token|"
+    r"password|secret|authorization)[\"']?\s*[:=]\s*[\"']?)([^\s\"',;}]+)"
+)
+
+
+def redact(text: str) -> str:
+    for name, value in os.environ.items():
+        if len(value) >= 8 and re.search(r"TOKEN|SECRET|PASSWORD|API_KEY|ACCESS_KEY", name):
+            text = text.replace(value, "[redacted]")
+    text = re.sub(r"(?i)\bBearer\s+[^\s\"',;}]+", "Bearer [redacted]", text)
+    text = re.sub(r"(?i)(https?://)[^/\s@]+@", r"\1[redacted]@", text)
+    text = _TOKEN.sub("[redacted]", text)
+    text = _ASSIGNMENT.sub(r"\1[redacted]", text)
+    return re.sub(r"[\x00-\x08\x0b-\x1f\x7f]", "", text)
+
+
+# Enough for a deep cause chain through the agent graph, small enough that a
+# failing loop cannot fill a session directory.
+REPORT_CHARS = 32_000
+
+
+def error_report(error: BaseException) -> str:
+    """The frames `error_details` deliberately omits, redacted and bounded.
+
+    Frames and exception messages only: locals are never captured, so a request
+    object or credential held in a stack frame cannot reach the file. Keep the
+    end when truncating -- the innermost frames are where the failure is.
+    """
+    text = redact("".join(traceback.format_exception(error)))
+    if len(text) <= REPORT_CHARS:
+        return text
+    return "[earlier frames omitted]\n" + text[-REPORT_CHARS:]
+
+
+def error_details(error: BaseException) -> dict:
+    """Keep bounded, redacted causes without traceback locals or request objects."""
+    return _error_details(error, set())
+
+
+def _error_details(error: BaseException, seen: set[int]) -> dict:
+    if id(error) in seen or len(seen) >= 16:
+        return {"type": type(error).__name__, "truncated": True}
+    seen.add(id(error))
+    if isinstance(error, BaseExceptionGroup) and error.exceptions:
+        return _error_details(error.exceptions[0], seen)
+    result = {"type": type(error).__name__}
+    status = getattr(error, "status_code", None)
+    if isinstance(status, int):
+        result["status"] = status
+    body = getattr(error, "body", None)
+    if isinstance(body, dict):
+        detail = body.get("error", body)
+        if isinstance(detail, dict):
+            for key in ("message", "code", "param", "type"):
+                value = detail.get(key)
+                if isinstance(value, str):
+                    result[f"provider_{key}"] = redact(value)[:4000]
+    if "provider_message" not in result:
+        result["message"] = redact(str(error))[:4000]
+    if error.__cause__ is not None:
+        result["cause"] = _error_details(error.__cause__, seen)
+    elif error.__context__ is not None and not error.__suppress_context__:
+        result["context"] = _error_details(error.__context__, seen)
+    return result
+
+
+TRANSIENT_TRANSPORT = frozenset(
+    {
+        "RemoteProtocolError",
+        "APIConnectionError",
+        "ConnectError",
+        "ConnectTimeout",
+        "ReadError",
+        "ReadTimeout",
+        "WriteError",
+        "WriteTimeout",
+        "APITimeoutError",
+        "IncompleteRead",
+        # A `claude:` CLI process ended mid-request; the retry starts another.
+        "ClaudeProcessError",
+        # A `claude:` request got no HTTP response; the retry forks the transcript.
+        "ClaudeConnectionError",
+    }
+)
+
+
+def transport_types(error: BaseException) -> set[str]:
+    """Name every exception in the bounded cause chain, never its text."""
+    names, detail = set(), error_details(error)
+    while detail:
+        names.add(detail["type"])
+        detail = detail.get("cause", detail.get("context", {}))
+    return names
+
+
+def transient(error: BaseException) -> bool:
+    """Whether the provider dropped the connection rather than answering.
+
+    A status code means the provider did answer: rate limits and server errors
+    need their own handling, so they are deliberately not transient here.
+    """
+    detail = error_details(error)
+    while detail:
+        if "status" in detail:
+            return False
+        detail = detail.get("cause", detail.get("context", {}))
+    return bool(transport_types(error) & TRANSIENT_TRANSPORT)
+
+
+def provider_context(model) -> dict[str, str]:
+    """Best-effort configured route, never requests, headers, or proxy credentials.
+
+    This names the parent model, not necessarily a failing delegated request.
+    Unresolved model strings must not trigger credential loading during failure.
+    """
+    result = {}
+    try:
+        if isinstance(model, str):
+            result["model"] = redact(model)
+            return result
+        result["model"] = redact(model.model_name)
+        provider = model.provider
+        if provider is not None:
+            result["provider"] = redact(provider.name)
+            url = urlsplit(str(provider.client.base_url))
+            if url.scheme in {"http", "https"} and url.hostname:
+                host = url.hostname
+                if ":" in host:
+                    host = f"[{host}]"
+                if url.port is not None:
+                    host += f":{url.port}"
+                # Drop userinfo, query, and fragment even for unfamiliar secrets.
+                result["base_url"] = redact(urlunsplit((url.scheme, host, url.path, "", "")))
+    except Exception:
+        # Diagnostics must never replace the original failure.
+        pass
+    return result
+
+
+def quota_message(error: BaseException) -> str | None:
+    """Classify bounded provider causes; never echo arbitrary response text."""
+    detail = error_details(error)
+    rate_limited = False
+    http_status = None
+    while detail:
+        if http_status is None:
+            http_status = detail.get("status")
+        text = " ".join(
+            str(detail.get(key, ""))
+            for key in ("provider_code", "provider_type", "provider_message", "message")
+        ).lower()
+        if any(
+            marker in text
+            for marker in (
+                "insufficient_quota",
+                "no credits remaining",
+                "credit balance is too low",
+                "billing_hard_limit_reached",
+                "exceeded your current quota",
+            )
+        ):
+            return (
+                "Provider quota or credits exhausted. Check usage and billing for the "
+                "selected provider account; a new login may not help. "
+                "See the saved session diagnostics."
+            )
+        rate_limited |= detail.get("status") == 429 or (
+            "status" not in detail
+            and any(marker in text for marker in ("rate_limit_error", "rate_limit_exceeded"))
+        )
+        detail = detail.get("cause", detail.get("context", {}))
+    if rate_limited:
+        return (
+            f"Provider rate limit reached{f' (HTTP {http_status})' if http_status else ''}. "
+            "Wait before retrying and check "
+            "the selected account's usage limits. See the saved session diagnostics."
+        )
+    return None
+
+
+def versions() -> dict[str, str]:
+    return {
+        package: version(package)
+        for package in ("pcode", "pydantic-ai-slim", "pydantic-ai-harness")
+    }

pcode/edit_preview.py

@@ -0,0 +1,158 @@
+"""Transient, line-buffered projections of tool arguments; never execute them."""
+
+from copy import deepcopy
+from pathlib import Path
+from time import monotonic
+
+from pydantic_ai.messages import (
+    FunctionToolCallEvent,
+    FunctionToolResultEvent,
+    PartDeltaEvent,
+    PartEndEvent,
+    PartStartEvent,
+    ToolCallPart,
+    ToolCallPartDelta,
+)
+from pydantic_core import from_json
+
+from pcode.edits import MAX_SOURCE, edit_text, sensitive_path
+from pcode.runtime import EditPreview
+
+
+class StreamingEditPreview:
+    def __init__(self, root: Path | None = None):
+        self.root = (root or Path.cwd()).resolve()
+        self.parts = {}
+        self.shown = {}
+        self.updated = {}
+        self.blocked = set()
+
+    def update(self, event):
+        clear = []
+        if isinstance(event, PartStartEvent):
+            if not isinstance(event.part, ToolCallPart):
+                return clear
+            index = event.index
+            if index in self.shown:
+                clear.append(EditPreview(f"edit-preview:{index}"))
+                self.shown.pop(index, None)
+            self.blocked.discard(index)
+            self.updated.pop(index, None)
+            self.parts[index] = deepcopy(event.part)
+        elif isinstance(event, PartDeltaEvent) and isinstance(event.delta, ToolCallPartDelta):
+            index = event.index
+            if index not in self.parts or index in self.blocked:
+                return clear
+            self.parts[index] = event.delta.apply(self.parts[index])
+        elif isinstance(event, PartEndEvent) and isinstance(event.part, ToolCallPart):
+            index = event.index
+            if index in self.blocked:
+                return clear
+            self.parts[index] = deepcopy(event.part)
+        elif isinstance(event, (FunctionToolCallEvent, FunctionToolResultEvent)):
+            call_id = event.part.tool_call_id
+            for index, part in list(self.parts.items()):
+                if part.tool_call_id == call_id:
+                    self.parts.pop(index)
+                    self.updated.pop(index, None)
+                    if self.shown.pop(index, None) is not None:
+                        clear.append(EditPreview(f"edit-preview:{index}"))
+            return clear
+        else:
+            return clear
+
+        part = self.parts[index]
+        if part.tool_name not in ("edit_file", "write_file", "run_code"):
+            return clear
+        if isinstance(part.args, str) and len(part.args) > MAX_SOURCE * 2:
+            self.blocked.add(index)
+            self.parts.pop(index)
+            if self.shown.pop(index, None) is not None:
+                clear.append(EditPreview(f"edit-preview:{index}"))
+            return clear
+        now = monotonic()
+        if isinstance(event, PartDeltaEvent) and now - self.updated.get(index, 0) < 0.05:
+            return clear
+        self.updated[index] = now
+        try:
+            if isinstance(part.args, str):
+                complete = from_json(part.args, allow_partial=True)
+                partial = from_json(part.args, allow_partial="trailing-strings")
+            else:
+                complete = partial = part.args
+        except ValueError:
+            return clear
+        if not isinstance(complete, dict) or not isinstance(partial, dict):
+            return clear
+        if part.tool_name == "run_code":
+            return clear + self._code_preview(index, partial, complete)
+        path = complete.get("path")
+        # Never expose content until the complete path is known and checked.
+        permitted = isinstance(path, str) and not sensitive_path(path)
+        if permitted:
+            try:
+                resolved = (self.root / path).resolve()
+                permitted = (
+                    not Path(path).is_absolute()
+                    and resolved.is_relative_to(self.root)
+                    and not sensitive_path(str(resolved.relative_to(self.root)))
+                )
+            except (OSError, ValueError, RuntimeError):
+                permitted = False
+        if not permitted:
+            if self.shown.pop(index, None) is not None:
+                clear.append(EditPreview(f"edit-preview:{index}"))
+            return clear
+        lines = []
+        fields = (
+            [("content", "+")]
+            if part.tool_name == "write_file"
+            else [("old_text", "-"), ("new_text", "+")]
+        )
+        pairs = [(partial, complete)]
+        if part.tool_name == "edit_file" and isinstance(partial.get("replacements"), list):
+            finished = complete.get("replacements", [])
+            if not isinstance(finished, list):
+                finished = []
+            pairs = [
+                (item, finished[i] if i < len(finished) and isinstance(finished[i], dict) else {})
+                for i, item in enumerate(partial["replacements"])
+                if isinstance(item, dict)
+            ]
+        for proposed, finished in pairs:
+            for field, prefix in fields:
+                text = proposed.get(field)
+                if not isinstance(text, str) or len(text) > MAX_SOURCE:
+                    continue
+                # Sanitize before clipping; unfinished strings expose only whole lines.
+                text = edit_text(text)
+                if field not in finished:
+                    text = text[: text.rfind("\n") + 1]
+                lines.extend(prefix + line for line in text.splitlines())
+        preview = EditPreview(f"edit-preview:{index}", edit_text(path), "\n".join(lines)[-8192:])
+        return clear + self._show(index, preview)
+
+    def _code_preview(self, index: int, partial: dict, complete: dict) -> list:
+        """Project a sandboxed snippet as it streams, before it is ever executed."""
+        code = partial.get("code")
+        if not isinstance(code, str) or len(code) > MAX_SOURCE:
+            if self.shown.pop(index, None) is not None:
+                return [EditPreview(f"edit-preview:{index}")]
+            return []
+        # Sanitize before clipping; an unfinished string exposes only whole lines.
+        text = edit_text(code)
+        if "code" not in complete:
+            text = text[: text.rfind("\n") + 1]
+        if not text:
+            # No complete line yet: an empty box would only flash open and shut.
+            return []
+        return self._show(
+            index,
+            EditPreview(f"edit-preview:{index}", "run_code", text[-8192:], kind="code"),
+        )
+
+    def _show(self, index: int, preview: EditPreview) -> list:
+        if preview == self.shown.get(index):
+            return []
+        self.shown[index] = preview
+        return [preview]