subcortex 0.3.0__py3-none-any.whl

subcortex/provision.py

@@ -0,0 +1,188 @@
+"""Backend environment provisioning for setup.
+
+The laya backend needs a heavy package (``laya-mlx`` on Apple Silicon, ``laya``
+elsewhere) next to subcortex itself. By default setup gives the daemon a
+dedicated virtualenv at ``~/.local/share/subcortex/venv`` holding both, so the
+user's own Python environments are never modified. Everything here reports
+problems as return values; nothing raises on expected failures.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Callable, Dict, List, Optional, Tuple
+
+from . import __version__
+from .config import venv_dir, venv_python
+
+
+
+def apple_silicon() -> bool:
+    return sys.platform == "darwin" and platform.machine() == "arm64"
+
+
+def laya_package() -> str:
+    return "laya-mlx" if apple_silicon() else "laya"
+
+
+def laya_module() -> str:
+    return "laya_mlx" if apple_silicon() else "laya"
+
+
+def daemon_python() -> str:
+    """The interpreter the daemon runs under: ``daemon_python`` from config (set by
+    setup), else the dedicated venv if present, else this interpreter."""
+    from .config import load_config
+
+    chosen = str(load_config().get("daemon_python") or "").strip()
+    if chosen and os.access(chosen, os.X_OK):
+        return chosen
+    return str(venv_python()) if venv_python().exists() else sys.executable
+
+
+def daemon_argv(python: Optional[str] = None) -> List[str]:
+    """How to start the daemon.
+
+    - Isolated (``-I``): PYTHONPATH and friends are ignored and the working
+      directory never lands on sys.path, so a project's own ``json.py`` can't
+      break the daemon or run inside it. Callers also start it from the data
+      dir, never the user's project.
+    - It runs *this* subcortex, whatever the interpreter: the backend venv may
+      hold an older copy of the package (a daemon of another version would
+      disagree with the hooks). The package is loaded from its own directory,
+      which then leaves sys.path again so the venv still provides the model.
+    """
+    python = python or daemon_python()
+    root = str(Path(__file__).resolve().parent.parent)
+    boot = (f"import sys; sys.path.insert(0, {root!r}); import subcortex; sys.path.remove({root!r}); "
+            "from subcortex.cli import main; sys.exit(main(['serve', '--foreground']))")
+    return [python, "-I", "-c", boot]
+
+
+def source_checkout() -> Optional[Path]:
+    """Repo root when subcortex runs from a source checkout (dev / editable install)."""
+    root = Path(__file__).resolve().parents[2]
+    pyproject = root / "pyproject.toml"
+    try:
+        if pyproject.is_file() and 'name = "subcortex"' in pyproject.read_text():
+            return root
+    except OSError:
+        pass
+    return None
+
+
+def subcortex_requirement() -> List[str]:
+    """pip arguments that install *this* subcortex into another environment:
+    the same source checkout, git commit or archive it was installed from
+    (PEP 610 ``direct_url.json``), else this version from PyPI."""
+    root = source_checkout()
+    if root:
+        return ["-e", str(root)]
+    try:
+        from importlib.metadata import distribution
+
+        direct = json.loads(distribution("subcortex").read_text("direct_url.json") or "null")
+    except Exception:
+        direct = None
+    if isinstance(direct, dict) and isinstance(direct.get("url"), str):
+        url = direct["url"]
+        vcs = direct.get("vcs_info") or {}
+        if vcs.get("vcs") == "git":
+            return [f"git+{url}@{vcs.get('commit_id') or vcs.get('requested_revision') or 'HEAD'}"]
+        if (direct.get("dir_info") or {}).get("editable") and url.startswith("file://"):
+            return ["-e", url[len("file://"):]]
+        return [url]
+    return [f"subcortex=={__version__}"]
+
+
+def probe(python: str) -> Dict[str, Optional[str]]:
+    """What ``python`` can import: {"python": version, "subcortex": version|None, "<laya module>": "yes"|None}."""
+    code = (
+        "import importlib.util, json, sys\n"
+        "out = {'python': sys.version.split()[0]}\n"
+        "try:\n"
+        "    import subcortex; out['subcortex'] = subcortex.__version__\n"
+        "except Exception:\n"
+        "    out['subcortex'] = None\n"
+        f"out['{laya_module()}'] = 'yes' if importlib.util.find_spec('{laya_module()}') else None\n"
+        "print(json.dumps(out))\n"
+    )
+    env = {k: v for k, v in os.environ.items() if k != "PYTHONPATH"}
+    try:
+        proc = subprocess.run([python, "-c", code], capture_output=True, text=True, timeout=60, env=env)
+        return json.loads(proc.stdout.strip().splitlines()[-1])
+    except Exception:
+        return {"python": None, "subcortex": None, laya_module(): None}
+
+
+def backend_ready(python: str) -> Tuple[bool, str]:
+    info = probe(python)
+    if not info.get("python"):
+        return False, f"{python} does not run"
+    if not info.get(laya_module()):
+        return False, f"{laya_package()} is not installed for {python}"
+    if info.get("subcortex") != __version__:
+        found = info.get("subcortex") or "not installed"
+        return False, f"subcortex there is {found}, this is {__version__}"
+    return True, f"{laya_package()} and subcortex {__version__} ready in {python}"
+
+
+def venv_is_foreign() -> Optional[str]:
+    """If the venv path is a symlink (e.g. into another project's env), its target."""
+    if venv_dir().is_symlink():
+        return os.readlink(venv_dir())
+    return None
+
+
+def create_venv(replace: bool = False) -> Tuple[bool, str]:
+    """Create the dedicated venv. ``replace`` drops a symlink/broken env first —
+    a symlink is only unlinked, never followed."""
+    try:
+        if venv_dir().is_symlink():
+            if not replace:
+                return False, f"{venv_dir()} is a symlink to {os.readlink(venv_dir())}"
+            venv_dir().unlink()
+        elif venv_dir().exists() and replace:
+            shutil.rmtree(venv_dir())
+        if not venv_python().exists():
+            venv_dir().parent.mkdir(parents=True, exist_ok=True)
+            subprocess.run([sys.executable, "-m", "venv", str(venv_dir())], check=True,
+                           capture_output=True, text=True, timeout=300)
+        return True, str(venv_dir())
+    except subprocess.CalledProcessError as exc:
+        return False, (exc.stderr or exc.stdout or str(exc)).strip()[-500:]
+    except Exception as exc:
+        return False, str(exc)
+
+
+def pip_install(python: str, args: List[str],
+                on_line: Optional[Callable[[str], None]] = None) -> Tuple[bool, str]:
+    """``python -m pip install <args>``; returns (ok, last lines of output)."""
+    env = {k: v for k, v in os.environ.items() if k != "PYTHONPATH"}
+    cmd = [python, "-m", "pip", "install", "--disable-pip-version-check", *args]
+    has_pip = subprocess.run([python, "-m", "pip", "--version"], capture_output=True, env=env).returncode == 0
+    if not has_pip and shutil.which("uv"):  # uv-managed environments ship without pip
+        cmd = ["uv", "pip", "install", "--python", python, *args]
+    try:
+        proc = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+                                text=True, env=env)
+    except OSError as exc:
+        return False, str(exc)
+    tail: List[str] = []
+    assert proc.stdout is not None
+    for line in proc.stdout:
+        tail = (tail + [line.rstrip()])[-15:]
+        if on_line:
+            on_line(line.rstrip())
+    return proc.wait() == 0, "\n".join(tail)
+
+
+def install_laya(python: str, on_line: Optional[Callable[[str], None]] = None) -> Tuple[bool, str]:
+    """Install the laya package and this subcortex into ``python``'s environment."""
+    return pip_install(python, [laya_package(), *subcortex_requirement()], on_line)

subcortex/service.py

@@ -0,0 +1,149 @@
+"""Start the daemon at login: a launchd agent (macOS) or a systemd user unit (Linux).
+
+The service runs ``<daemon python> -m subcortex serve --foreground`` and is
+restarted only if it crashes (a second instance exits 0 when the daemon is
+already running, so there is no restart loop). All system commands go through
+``runner`` so tests never touch launchctl/systemctl.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import sys
+from pathlib import Path
+from typing import Callable, Dict, List, Optional, Sequence
+from xml.sax.saxutils import escape
+
+from .config import data_dir, log_path
+from .provision import daemon_argv, daemon_python
+
+LABEL = "ai.subcortex.daemon"
+Runner = Callable[[Sequence[str]], subprocess.CompletedProcess]
+
+
+def _run(argv: Sequence[str]) -> subprocess.CompletedProcess:
+    return subprocess.run(list(argv), capture_output=True, text=True, timeout=30)
+
+
+def platform_kind() -> Optional[str]:
+    if sys.platform == "darwin":
+        return "launchd"
+    if sys.platform.startswith("linux"):
+        return "systemd"
+    return None
+
+
+def unit_path() -> Optional[Path]:
+    kind = platform_kind()
+    if kind == "launchd":
+        return Path.home() / "Library" / "LaunchAgents" / f"{LABEL}.plist"
+    if kind == "systemd":
+        xdg = os.environ.get("XDG_CONFIG_HOME", "").strip()
+        return (Path(xdg) if xdg else Path.home() / ".config") / "systemd" / "user" / "subcortex.service"
+    return None
+
+
+def _environment() -> Dict[str, str]:
+    env = {"PATH": os.environ.get("PATH", "/usr/bin:/bin")}
+    for key in ("SUBCORTEX_CONFIG", "SUBCORTEX_DATA_DIR"):
+        if os.environ.get(key):
+            env[key] = os.environ[key]
+    return env
+
+
+def render(python: Optional[str] = None) -> str:
+    argv = daemon_argv(python or daemon_python())  # isolated; see provision.daemon_argv
+    workdir = str(data_dir())
+    env = _environment()
+    if platform_kind() == "launchd":
+        args = "".join(f"\n    <string>{escape(a)}</string>" for a in argv)
+        envs = "".join(f"\n    <key>{escape(k)}</key><string>{escape(v)}</string>" for k, v in env.items())
+        return f"""<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>{LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>{args}
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>{envs}
+  </dict>
+  <key>WorkingDirectory</key><string>{escape(workdir)}</string>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key>
+  <dict><key>SuccessfulExit</key><false/></dict>
+  <key>ThrottleInterval</key><integer>30</integer>
+  <key>StandardOutPath</key><string>{escape(str(log_path()))}</string>
+  <key>StandardErrorPath</key><string>{escape(str(log_path()))}</string>
+</dict>
+</plist>
+"""
+    exec_start = " ".join(_systemd_quote(a) for a in argv)
+    env_lines = "\n".join(f"Environment={_systemd_quote(f'{k}={v}')}" for k, v in env.items())
+    return f"""[Unit]
+Description=subcortex decision daemon
+
+[Service]
+ExecStart={exec_start}
+WorkingDirectory={_systemd_quote(workdir)}
+{env_lines}
+Restart=on-failure
+RestartSec=30
+
+[Install]
+WantedBy=default.target
+"""
+
+
+def _systemd_quote(value: str) -> str:
+    return '"' + value.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+def install(python: Optional[str] = None, runner: Runner = _run) -> List[str]:
+    """Write and load the unit; returns human-readable notes (raises RuntimeError on failure)."""
+    path = unit_path()
+    if path is None:
+        raise RuntimeError(f"no login service support for {sys.platform}; "
+                           "hooks still start the daemon on demand")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(render(python))
+    notes = [f"wrote {path}"]
+    if platform_kind() == "launchd":
+        domain = f"gui/{os.getuid()}"
+        runner(["launchctl", "bootout", f"{domain}/{LABEL}"])  # reload if already loaded
+        result = runner(["launchctl", "bootstrap", domain, str(path)])
+        if result.returncode != 0:
+            result = runner(["launchctl", "load", "-w", str(path)])
+        if result.returncode != 0:
+            raise RuntimeError(f"launchctl could not load {path}: {(result.stderr or '').strip()}")
+        notes.append("loaded with launchctl (starts at every login)")
+    else:
+        for argv in (["systemctl", "--user", "daemon-reload"],
+                     ["systemctl", "--user", "enable", "--now", "subcortex.service"]):
+            result = runner(argv)
+            if result.returncode != 0:
+                raise RuntimeError(f"{' '.join(argv)} failed: {(result.stderr or '').strip()}")
+        notes.append("enabled with systemctl --user (starts at every login)")
+    return notes
+
+
+def uninstall(runner: Runner = _run) -> List[str]:
+    path = unit_path()
+    if path is None or not path.exists():
+        return ["no login service installed"]
+    if platform_kind() == "launchd":
+        runner(["launchctl", "bootout", f"gui/{os.getuid()}/{LABEL}"])
+    else:
+        runner(["systemctl", "--user", "disable", "--now", "subcortex.service"])
+    path.unlink()
+    if platform_kind() == "systemd":
+        runner(["systemctl", "--user", "daemon-reload"])
+    return [f"removed {path}"]
+
+
+def status() -> Dict[str, object]:
+    path = unit_path()
+    return {"supported": path is not None, "installed": bool(path and path.exists()),
+            "path": str(path) if path else None}

subcortex/state.py

@@ -0,0 +1,137 @@
+"""Per-session state files, shared by hook processes and the daemon.
+
+Many sessions of many TUIs run at once against one data dir, and a single
+session's hooks can overlap (e.g. a restore on SessionStart and on the next
+prompt). So every file here is:
+
+- keyed by (TUI, session id): collision-free across TUIs and across ids that
+  sanitize alike, and never able to escape its directory;
+- written atomically (temp file + rename), so readers never see a torn file;
+- private (dirs 0700, files 0600), since they hold prompts and conversation text;
+- changed under a per-session lock (``locked``), so read-modify-write and
+  consume-once operations don't race across threads or processes.
+
+Everything fails open: errors surface as None/False/TimeoutError for the
+caller to swallow, never as a changed TUI outcome.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import fcntl
+import hashlib
+import json
+import os
+import time
+from pathlib import Path
+from typing import Any, Dict, Iterator, Optional
+
+from .config import data_dir
+
+LOCK_WAIT_S = 1.0          # a hook has a few seconds in total; give up well before that
+_LOCK_STRIPES = 64         # fixed lock files, never deleted (deleting a lock file breaks flock)
+_PRUNE_EVERY_S = 600
+
+
+def key(tui: Any, session_id: Any) -> Optional[str]:
+    """Filename-safe, collision-free key for one TUI session (None without a session id)."""
+    if not isinstance(session_id, str) or not session_id.strip():
+        return None
+    sid = session_id.strip()
+    ns = tui.strip() if isinstance(tui, str) and tui.strip() else "_"
+    digest = hashlib.sha256(f"{ns}\0{sid}".encode("utf-8", "replace")).hexdigest()[:24]
+    readable = "".join(c if c.isalnum() or c in "-_" else "_" for c in f"{ns}-{sid}")[:64]
+    return f"{readable}-{digest}"
+
+
+def _private(directory: Path) -> Path:
+    """Create ``directory`` owner-only. Only writers call this. The data dir
+    itself is created 0700 but never re-permissioned: SUBCORTEX_DATA_DIR may
+    point at a directory the user shares on purpose. Our own subdirectories
+    (and the 0600 files in them) carry the privacy."""
+    root = data_dir()
+    if not root.exists():
+        root.mkdir(mode=0o700, parents=True, exist_ok=True)
+    directory.mkdir(mode=0o700, parents=True, exist_ok=True)
+    try:
+        if directory != root and directory.stat().st_mode & 0o077:
+            os.chmod(directory, 0o700)  # mkdir's mode is masked by umask
+    except OSError:
+        pass
+    return directory
+
+
+def path(kind: str, tui: Any, session_id: Any) -> Optional[Path]:
+    """Where this session's ``kind`` file lives. Creates nothing."""
+    k = key(tui, session_id)
+    return data_dir() / kind / f"{k}.json" if k else None
+
+
+def write_json(target: Path, data: Dict[str, Any]) -> None:
+    _private(target.parent)
+    tmp = target.parent / f".tmp-{os.getpid()}-{os.urandom(6).hex()}.json"
+    fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as fh:
+            json.dump(data, fh, ensure_ascii=False)
+        os.replace(tmp, target)
+    except BaseException:
+        with contextlib.suppress(OSError):
+            os.unlink(tmp)
+        raise
+
+
+def read_json(target: Path) -> Optional[Dict[str, Any]]:
+    try:
+        data = json.loads(target.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+@contextlib.contextmanager
+def locked(k: str, wait_s: Optional[float] = None) -> Iterator[None]:
+    """Exclusive per-session lock across threads and processes; TimeoutError if busy."""
+    wait_s = LOCK_WAIT_S if wait_s is None else wait_s
+    stripe = int(hashlib.sha256(k.encode()).hexdigest()[:8], 16) % _LOCK_STRIPES
+    lock_path = _private(data_dir() / "locks") / f"{stripe:02d}.lock"
+    fd = os.open(lock_path, os.O_RDWR | os.O_CREAT, 0o600)
+    try:
+        deadline = time.monotonic() + wait_s
+        while True:
+            try:
+                fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                break
+            except BlockingIOError:
+                if time.monotonic() >= deadline:
+                    raise TimeoutError(f"state lock busy: {k}") from None
+                time.sleep(0.01)
+        try:
+            yield
+        finally:
+            fcntl.flock(fd, fcntl.LOCK_UN)
+    finally:
+        os.close(fd)
+
+
+def prune(kind: str, max_age_s: float) -> None:
+    """Delete this kind's files older than ``max_age_s``; runs at most every few minutes."""
+    try:
+        directory = data_dir() / kind
+        if not directory.is_dir():
+            return
+        stamp = directory / ".pruned"
+        now = time.time()
+        if stamp.exists() and now - stamp.stat().st_mtime < _PRUNE_EVERY_S:
+            return
+        stamp.touch()
+        for old in [*directory.glob("*.json"), *directory.glob("*.claim")]:
+            with contextlib.suppress(OSError):
+                if now - old.stat().st_mtime > max_age_s:
+                    old.unlink()
+        for tmp in directory.glob(".tmp-*"):  # left behind by a killed writer
+            with contextlib.suppress(OSError):
+                if now - tmp.stat().st_mtime > 60:
+                    tmp.unlink()
+    except OSError:
+        pass

subcortex/transcript.py

@@ -0,0 +1,211 @@
+"""Shape-tolerant transcript reading for compaction snapshots.
+
+Every TUI records conversations differently (Claude Code JSONL entries with a
+nested ``message``, Codex rollout lines wrapping a ``payload``, Gemini-style
+``parts``, whole-file JSON with a ``messages`` array, ...). ``last_messages``
+extracts the final few user/assistant texts from any of them and never raises.
+Only the tail of large files is read.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional
+
+TAIL_BYTES = 1_000_000
+WHOLE_FILE_MAX_BYTES = 20_000_000
+
+_USER_ROLES = {"user", "human"}
+_ASSISTANT_ROLES = {"assistant", "model", "gemini", "ai", "agent"}
+_TEXT_BLOCK_TYPES = {"text", "input_text", "output_text"}
+# Harness-injected pseudo-messages such as <environment_context>…
+_INJECTED_RE = re.compile(r"<[a-z][\w-]*(?:\s[^>]*)?>", re.IGNORECASE)  # matched on stripped text
+_INJECTED_PREFIXES = ("# AGENTS.md instructions",)  # Codex
+# ...except wrappers around the user's own words (Cursor: <user_query>,
+# Cline: <user_input mode="act">).
+_USER_WRAPPERS = ("user_query", "user_message", "user_input")
+
+
+def _unwrap_user(text: str) -> Optional[str]:
+    """The words inside <user_query>…</user_query> (attributes allowed), else
+    None. Plain string operations: a regex here backtracked cubically on long
+    whitespace runs."""
+    for tag in _USER_WRAPPERS:
+        opening, closing = f"<{tag}", f"</{tag}>"
+        if not (text.startswith(opening) and text.endswith(closing)):
+            continue
+        rest = text[len(opening):]
+        if not rest or rest[0] not in "> \t\n":
+            continue  # a different tag that merely starts the same way
+        end = rest.find(">")
+        if end == -1 or end > len(rest) - len(closing):
+            continue
+        return rest[end + 1:len(rest) - len(closing)].strip()
+    return None
+
+
+def _role(value: Any) -> Optional[str]:
+    if not isinstance(value, str):
+        return None
+    lowered = value.strip().lower()
+    if lowered in _USER_ROLES:
+        return "user"
+    if lowered in _ASSISTANT_ROLES:
+        return "assistant"
+    return None
+
+
+def _text(content: Any) -> str:
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts = []
+        for block in content:
+            if isinstance(block, str):
+                parts.append(block)
+            elif isinstance(block, dict) and isinstance(block.get("text"), str):
+                if block.get("type") in (None, *_TEXT_BLOCK_TYPES):
+                    parts.append(block["text"])
+        return "\n".join(p for p in parts if p)
+    if isinstance(content, dict) and isinstance(content.get("text"), str):
+        return content["text"]
+    return ""
+
+
+def _display_text(entry: Dict[str, Any]) -> str:
+    """What the user typed, without the hook context the TUI appended to the
+    model-bound message (Gemini CLI ``displayContent``, Qwen Code
+    ``systemPayload.displayText``)."""
+    if "displayContent" in entry:
+        return _text(entry["displayContent"])
+    payload = entry.get("systemPayload")
+    if isinstance(payload, dict) and isinstance(payload.get("displayText"), str):
+        return payload["displayText"]
+    return ""
+
+
+def _without_our_context(text: str) -> str:
+    """Drop what subcortex itself injected (hint lines, restored-context blocks),
+    so a snapshot never carries — or compounds — our own output."""
+    if "[subcortex]" not in text:
+        return text
+    kept, skipping = [], False
+    for line in text.split("\n"):
+        if line.lstrip().startswith("[subcortex] Recent conversation from before context compaction"):
+            skipping = True  # a restore block runs to the next blank line
+            continue
+        if skipping:
+            if line.strip():
+                continue
+            skipping = False
+        if line.lstrip().startswith("[subcortex]"):
+            continue
+        kept.append(line)
+    return "\n".join(kept)
+
+
+def message_from_entry(entry: Any) -> Optional[Dict[str, str]]:
+    """``{"role", "text"}`` for one transcript record, or None if it isn't a
+    user/assistant message with text."""
+    if not isinstance(entry, dict):
+        return None
+    if entry.get("isMeta") or entry.get("isCompactSummary") or entry.get("isSidechain") \
+            or entry.get("synthetic_reason"):
+        return None  # reminders, compaction summaries, subagent turns, injected items
+    payload = entry.get("payload")
+    if isinstance(payload, dict):
+        return message_from_entry(payload)
+    kind = entry.get("type")
+    if isinstance(kind, str) and kind.endswith(".message"):  # Copilot session events
+        data = entry.get("data") if isinstance(entry.get("data"), dict) else entry
+        role = _role(kind[: -len(".message")])
+        text = _text(data.get("content", data.get("text", data.get("message")))).strip()
+        return {"role": role, "text": text} if role and text else None
+    message = entry.get("message")
+    if isinstance(message, dict):
+        role = _role(message.get("role")) or _role(entry.get("type")) or _role(entry.get("role"))
+        text = _text(message.get("content", message.get("parts")))
+    else:
+        role = _role(entry.get("role")) or _role(entry.get("type")) or _role(entry.get("author"))
+        text = _text(entry.get("content", entry.get("parts", entry.get("text"))))
+        if not text and isinstance(message, str):
+            text = message
+    text = _without_our_context(_display_text(entry) or text).strip()
+    wrapped = _unwrap_user(text)
+    if wrapped is not None:
+        text = wrapped
+    elif _INJECTED_RE.match(text) or text.startswith(_INJECTED_PREFIXES):
+        return None
+    if role is None or not text:
+        return None
+    return {"role": role, "text": text}
+
+
+def read_tail(path: Path) -> str:
+    size = path.stat().st_size
+    with open(path, "rb") as fh:
+        if size > TAIL_BYTES:
+            fh.seek(size - TAIL_BYTES)
+            fh.readline()  # drop the partial first line
+        return fh.read().decode("utf-8", errors="replace")
+
+
+def _unwrap(whole: Any) -> List[Any]:
+    if isinstance(whole, list):
+        return whole
+    if isinstance(whole, dict):
+        for key in ("messages", "history", "items", "conversation"):
+            if isinstance(whole.get(key), list):
+                return whole[key]
+        return [whole]
+    return []
+
+
+def _entries(path: Path) -> Iterable[Any]:
+    """JSONL records from the file's tail, or the message list of a whole-JSON file."""
+    raw = read_tail(path)
+    entries, bad = [], 0
+    for line in raw.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            entries.append(json.loads(line))
+        except ValueError:
+            bad += 1
+    if entries and bad <= len(entries):  # JSONL (a stray partial line is fine)
+        return _unwrap(entries[0]) if len(entries) == 1 else entries
+    if path.stat().st_size > WHOLE_FILE_MAX_BYTES:  # pretty-printed and huge: give up
+        return []
+    try:
+        return _unwrap(json.loads(path.read_text(encoding="utf-8", errors="replace")))
+    except ValueError:
+        return []
+
+
+def messages_from_entries(entries: Iterable[Any], limit: int, max_chars: int) -> List[Dict[str, str]]:
+    out: List[Dict[str, str]] = []
+    for entry in entries:
+        msg = message_from_entry(entry)
+        if msg is None:
+            continue
+        msg["text"] = msg["text"][:max_chars]
+        if out and out[-1] == msg:  # rollouts often log the same message twice
+            continue
+        out.append(msg)
+    return out[-limit:] if limit > 0 else []
+
+
+def last_messages(path: Any, limit: int = 5, max_chars: int = 500) -> List[Dict[str, str]]:
+    """Last ``limit`` user/assistant messages from a transcript file; [] on any problem."""
+    try:
+        if not isinstance(path, str) or not path:
+            return []
+        p = Path(path).expanduser()
+        if not p.is_file():
+            return []
+        return messages_from_entries(_entries(p), limit, max_chars)
+    except Exception:
+        return []