codebee 0.1.101 → 0.1.103

package/app/core/tlsctx.py

@@ -1,64 +1,64 @@
-# -*- coding: utf-8 -*-
-"""HTTPS 证书校验上下文：补齐 macOS 上 Python 缺失的 CA 源（不关校验）。
-
-现象：用官方 pkg 装 Node 的 Mac 上往往再装 python.org 的 Python，它不读
-系统钥匙串，默认验证路径下没有根证书，所有 HTTPS 请求报
-CERTIFICATE_VERIFY_FAILED（unable to get local issuer certificate）。
-
-修法是给默认上下文**追加**可用 CA 源，校验语义只增不减：
-  1. certifi（装了就用，跨平台最全）；
-  2. /etc/ssl/cert.pem（macOS 系统自带 CA 束，Catalina 起就有）。
-两个都拿不到时返回默认上下文——报错与旧行为一致，绝不静默关校验。
-"""
-import ssl
-import sys
-
-
-def cafiles():
-    """候选 CA 束路径；坏路径/不存在由 load_verify_locations 抛错后被吞。"""
-    out = []
-    try:
-        import certifi
-        out.append(certifi.where())
-    except Exception:
-        pass
-    if sys.platform == "darwin":
-        out.append("/etc/ssl/cert.pem")
-    return out
-
-
-def _build():
-    ctx = ssl.create_default_context()
-    for f in cafiles():
-        try:
-            ctx.load_verify_locations(cafile=f)
-        except Exception:
-            pass
-    return ctx
-
-
-_CTX = None
-
-
-def context():
-    """带兜底 CA 源的 ssl.SSLContext（进程内缓存；校验语义与默认一致）。"""
-    global _CTX
-    if _CTX is None:
-        _CTX = _build()
-    return _CTX
-
-
-def humanize(err_text):
-    """证书验证失败 → 可行动的人话提示（非证书类错误原样返回）。
-
-    兜底 CA 仍验证失败只剩两类真实原因：本机代理对 HTTPS 做 TLS 拦截
-    （其根证书只在系统钥匙串/浏览器里，Python 的静态 CA 束不认），或极端
-    环境连 /etc/ssl/cert.pem 都没有。SSL_CERT_FILE 是 OpenSSL 标准逃生门，
-    create_default_context() 本就吃它，无需额外代码。"""
-    text = str(err_text or "")
-    if "CERTIFICATE_VERIFY_FAILED" not in text:
-        return text
-    return (text + " —— 证书验证仍失败：① 若开着代理/安全软件且开启了 HTTPS 拦截，"
-            "关掉拦截，或把其根证书导出后设环境变量 SSL_CERT_FILE 指向它再启动；"
-            "② 确认系统存在 /etc/ssl/cert.pem；③ 刚升级过 CodeBee 的话，"
-            "旧服务进程可能还在跑——关掉终端窗口重开")
+# -*- coding: utf-8 -*-
+"""HTTPS 证书校验上下文：补齐 macOS 上 Python 缺失的 CA 源（不关校验）。
+
+现象：用官方 pkg 装 Node 的 Mac 上往往再装 python.org 的 Python，它不读
+系统钥匙串，默认验证路径下没有根证书，所有 HTTPS 请求报
+CERTIFICATE_VERIFY_FAILED（unable to get local issuer certificate）。
+
+修法是给默认上下文**追加**可用 CA 源，校验语义只增不减：
+  1. certifi（装了就用，跨平台最全）；
+  2. /etc/ssl/cert.pem（macOS 系统自带 CA 束，Catalina 起就有）。
+两个都拿不到时返回默认上下文——报错与旧行为一致，绝不静默关校验。
+"""
+import ssl
+import sys
+
+
+def cafiles():
+    """候选 CA 束路径；坏路径/不存在由 load_verify_locations 抛错后被吞。"""
+    out = []
+    try:
+        import certifi
+        out.append(certifi.where())
+    except Exception:
+        pass
+    if sys.platform == "darwin":
+        out.append("/etc/ssl/cert.pem")
+    return out
+
+
+def _build():
+    ctx = ssl.create_default_context()
+    for f in cafiles():
+        try:
+            ctx.load_verify_locations(cafile=f)
+        except Exception:
+            pass
+    return ctx
+
+
+_CTX = None
+
+
+def context():
+    """带兜底 CA 源的 ssl.SSLContext（进程内缓存；校验语义与默认一致）。"""
+    global _CTX
+    if _CTX is None:
+        _CTX = _build()
+    return _CTX
+
+
+def humanize(err_text):
+    """证书验证失败 → 可行动的人话提示（非证书类错误原样返回）。
+
+    兜底 CA 仍验证失败只剩两类真实原因：本机代理对 HTTPS 做 TLS 拦截
+    （其根证书只在系统钥匙串/浏览器里，Python 的静态 CA 束不认），或极端
+    环境连 /etc/ssl/cert.pem 都没有。SSL_CERT_FILE 是 OpenSSL 标准逃生门，
+    create_default_context() 本就吃它，无需额外代码。"""
+    text = str(err_text or "")
+    if "CERTIFICATE_VERIFY_FAILED" not in text:
+        return text
+    return (text + " —— 证书验证仍失败：① 若开着代理/安全软件且开启了 HTTPS 拦截，"
+            "关掉拦截，或把其根证书导出后设环境变量 SSL_CERT_FILE 指向它再启动；"
+            "② 确认系统存在 /etc/ssl/cert.pem；③ 刚升级过 CodeBee 的话，"
+            "旧服务进程可能还在跑——关掉终端窗口重开")

package/app/core/token_meter.py

@@ -1,148 +1,148 @@
-# -*- coding: utf-8 -*-
-"""Token 压力估算：按 run 累计 usage，给出「已用/容量」压力比。
-
-设计稿：docs/migration/02-context-compaction.md §1C。
-参考 dsh packages/llm/token-meter/src/index.ts：滑动窗口 + usage 锚点 + 失败重定价。
-
-Tutti 简化实现：每 run 一个累计窗口（deque 有上限），usage 来自
-runner._parse_codex_jsonl / _parse_claude_json 已解析的字段；
-容量查 DEFAULT_CAPACITY 表（可被 data/model_capacity.json 覆盖）。
-"""
-from __future__ import annotations
-
-import json
-import logging
-import threading
-import time
-from collections import deque
-from pathlib import Path
-
-log = logging.getLogger(__name__)
-
-# 默认模型容量（token）。未命中 key 时用 "" 兜底行。
-DEFAULT_CAPACITY = {
-    "": 128_000,
-    "gpt-5": 400_000,
-    "gpt-5.5": 400_000,
-    "deepseek-chat": 128_000,
-    "deepseek-reasoner": 64_000,
-    "qwen3-max": 256_000,
-    "qwen3.8-flash": 256_000,
-}
-
-# 压缩触发阈值（设计稿 §1B 默认 0.8，可被 orchestration.json 覆盖）
-DEFAULT_PRESSURE_THRESHOLD = 0.8
-
-# 容量覆盖文件（热改立即生效）
-_CAPACITY_FILE = Path(__file__).resolve().parents[2] / "data" / "model_capacity.json"
-
-
-def _load_capacity():
-    """默认表 + 可选覆盖文件合并。文件缺失/坏 JSON 静默用默认。"""
-    cap = dict(DEFAULT_CAPACITY)
-    try:
-        if _CAPACITY_FILE.is_file():
-            data = json.loads(_CAPACITY_FILE.read_text(encoding="utf-8"))
-            if isinstance(data, dict):
-                cap.update({str(k): int(v) for k, v in data.items()})
-    except Exception:
-        pass
-    return cap
-
-
-class TokenMeter:
-    """每 run 独立累计窗口；线程安全。"""
-
-    def __init__(self, capacity=None, *, window_size=200):
-        self._capacity_override = capacity
-        self._window_size = window_size
-        self._lock = threading.Lock()
-        # run_id -> deque[(ts, input, output, reasoning, cached)]
-        self._windows: dict = {}
-        # run_id -> 最后一次见到的 model 名（pressure_ratio 未显式传 model 时用）
-        self._last_model: dict = {}
-        self._cap_cache = None
-        self._cap_mtime = 0.0
-
-    def _capacity(self):
-        """容量表（带 mtime 缓存，热改 data/model_capacity.json 立即生效）。"""
-        try:
-            mtime = _CAPACITY_FILE.stat().st_mtime
-        except OSError:
-            mtime = 0.0
-        if self._cap_cache is None or mtime != self._cap_mtime:
-            if self._capacity_override is not None:
-                self._cap_cache = dict(self._capacity_override)
-            else:
-                self._cap_cache = _load_capacity()
-            self._cap_mtime = mtime
-        return self._cap_cache
-
-    def accumulate(self, run_id: str, usage, model: str = ""):
-        """记录一次调用的 usage。usage 字段缺失按 0 处理；usage=None 跳过。
-
-        cached 单独记录但不计入 used()——缓存读不占新一轮上下文压力
-        （与 runner._parse_claude_json 的口径一致：cached 是省钱的部分）。
-        """
-        if not usage:
-            return
-        with self._lock:
-            if model:
-                self._last_model[run_id] = model
-            window = self._windows.setdefault(run_id, deque(maxlen=self._window_size))
-            window.append((
-                time.time(),
-                int(usage.get("input") or 0),
-                int(usage.get("output") or 0),
-                int(usage.get("reasoning") or 0),
-                int(usage.get("cached") or 0),
-            ))
-
-    def used(self, run_id: str) -> int:
-        """窗口内累计（input + output + reasoning），不含 cached。"""
-        with self._lock:
-            window = self._windows.get(run_id)
-            if not window:
-                return 0
-            return sum(i + o + r for _, i, o, r, _ in window)
-
-    def cached(self, run_id: str) -> int:
-        with self._lock:
-            window = self._windows.get(run_id)
-            if not window:
-                return 0
-            return sum(c for _, _, _, _, c in window)
-
-    def pressure_ratio(self, run_id: str, model: str = "") -> float:
-        """已用 / 容量。model 未传时用该 run 最后一次见到的模型名。"""
-        cap_table = self._capacity()
-        with self._lock:
-            m = model or self._last_model.get(run_id, "")
-        cap = cap_table.get(m, cap_table.get("", 128_000))
-        return self.used(run_id) / max(cap, 1)
-
-    def capacity(self, model: str = "") -> int:
-        """模型上下文容量（未命中用默认行）。"""
-        cap_table = self._capacity()
-        return cap_table.get(model or "", cap_table.get("", 128_000))
-
-    def last_context(self, run_id: str) -> int:
-        """最近一次调用的 input+output+reasoning——下个请求要重发的上下文锚点。
-
-        used() 是窗口累计（多次调用叠加，系统性偏大，适合做响应式预算闸）；
-        事前预检判断「这个请求会不会被拒」要用最近一次的真实上下文体量，
-        两者口径不同不可混用（借鉴 freebuff base-chat 每步容量重估）。"""
-        with self._lock:
-            window = self._windows.get(run_id)
-            if not window:
-                return 0
-            _, i, o, r, _ = window[-1]
-            return i + o + r
-
-    def reset(self, run_id: str):
-        with self._lock:
-            self._windows.pop(run_id, None)
-            self._last_model.pop(run_id, None)
-
-
+# -*- coding: utf-8 -*-
+"""Token 压力估算：按 run 累计 usage，给出「已用/容量」压力比。
+
+设计稿：docs/migration/02-context-compaction.md §1C。
+参考 dsh packages/llm/token-meter/src/index.ts：滑动窗口 + usage 锚点 + 失败重定价。
+
+Tutti 简化实现：每 run 一个累计窗口（deque 有上限），usage 来自
+runner._parse_codex_jsonl / _parse_claude_json 已解析的字段；
+容量查 DEFAULT_CAPACITY 表（可被 data/model_capacity.json 覆盖）。
+"""
+from __future__ import annotations
+
+import json
+import logging
+import threading
+import time
+from collections import deque
+from pathlib import Path
+
+log = logging.getLogger(__name__)
+
+# 默认模型容量（token）。未命中 key 时用 "" 兜底行。
+DEFAULT_CAPACITY = {
+    "": 128_000,
+    "gpt-5": 400_000,
+    "gpt-5.5": 400_000,
+    "deepseek-chat": 128_000,
+    "deepseek-reasoner": 64_000,
+    "qwen3-max": 256_000,
+    "qwen3.8-flash": 256_000,
+}
+
+# 压缩触发阈值（设计稿 §1B 默认 0.8，可被 orchestration.json 覆盖）
+DEFAULT_PRESSURE_THRESHOLD = 0.8
+
+# 容量覆盖文件（热改立即生效）
+_CAPACITY_FILE = Path(__file__).resolve().parents[2] / "data" / "model_capacity.json"
+
+
+def _load_capacity():
+    """默认表 + 可选覆盖文件合并。文件缺失/坏 JSON 静默用默认。"""
+    cap = dict(DEFAULT_CAPACITY)
+    try:
+        if _CAPACITY_FILE.is_file():
+            data = json.loads(_CAPACITY_FILE.read_text(encoding="utf-8"))
+            if isinstance(data, dict):
+                cap.update({str(k): int(v) for k, v in data.items()})
+    except Exception:
+        pass
+    return cap
+
+
+class TokenMeter:
+    """每 run 独立累计窗口；线程安全。"""
+
+    def __init__(self, capacity=None, *, window_size=200):
+        self._capacity_override = capacity
+        self._window_size = window_size
+        self._lock = threading.Lock()
+        # run_id -> deque[(ts, input, output, reasoning, cached)]
+        self._windows: dict = {}
+        # run_id -> 最后一次见到的 model 名（pressure_ratio 未显式传 model 时用）
+        self._last_model: dict = {}
+        self._cap_cache = None
+        self._cap_mtime = 0.0
+
+    def _capacity(self):
+        """容量表（带 mtime 缓存，热改 data/model_capacity.json 立即生效）。"""
+        try:
+            mtime = _CAPACITY_FILE.stat().st_mtime
+        except OSError:
+            mtime = 0.0
+        if self._cap_cache is None or mtime != self._cap_mtime:
+            if self._capacity_override is not None:
+                self._cap_cache = dict(self._capacity_override)
+            else:
+                self._cap_cache = _load_capacity()
+            self._cap_mtime = mtime
+        return self._cap_cache
+
+    def accumulate(self, run_id: str, usage, model: str = ""):
+        """记录一次调用的 usage。usage 字段缺失按 0 处理；usage=None 跳过。
+
+        cached 单独记录但不计入 used()——缓存读不占新一轮上下文压力
+        （与 runner._parse_claude_json 的口径一致：cached 是省钱的部分）。
+        """
+        if not usage:
+            return
+        with self._lock:
+            if model:
+                self._last_model[run_id] = model
+            window = self._windows.setdefault(run_id, deque(maxlen=self._window_size))
+            window.append((
+                time.time(),
+                int(usage.get("input") or 0),
+                int(usage.get("output") or 0),
+                int(usage.get("reasoning") or 0),
+                int(usage.get("cached") or 0),
+            ))
+
+    def used(self, run_id: str) -> int:
+        """窗口内累计（input + output + reasoning），不含 cached。"""
+        with self._lock:
+            window = self._windows.get(run_id)
+            if not window:
+                return 0
+            return sum(i + o + r for _, i, o, r, _ in window)
+
+    def cached(self, run_id: str) -> int:
+        with self._lock:
+            window = self._windows.get(run_id)
+            if not window:
+                return 0
+            return sum(c for _, _, _, _, c in window)
+
+    def pressure_ratio(self, run_id: str, model: str = "") -> float:
+        """已用 / 容量。model 未传时用该 run 最后一次见到的模型名。"""
+        cap_table = self._capacity()
+        with self._lock:
+            m = model or self._last_model.get(run_id, "")
+        cap = cap_table.get(m, cap_table.get("", 128_000))
+        return self.used(run_id) / max(cap, 1)
+
+    def capacity(self, model: str = "") -> int:
+        """模型上下文容量（未命中用默认行）。"""
+        cap_table = self._capacity()
+        return cap_table.get(model or "", cap_table.get("", 128_000))
+
+    def last_context(self, run_id: str) -> int:
+        """最近一次调用的 input+output+reasoning——下个请求要重发的上下文锚点。
+
+        used() 是窗口累计（多次调用叠加，系统性偏大，适合做响应式预算闸）；
+        事前预检判断「这个请求会不会被拒」要用最近一次的真实上下文体量，
+        两者口径不同不可混用（借鉴 freebuff base-chat 每步容量重估）。"""
+        with self._lock:
+            window = self._windows.get(run_id)
+            if not window:
+                return 0
+            _, i, o, r, _ = window[-1]
+            return i + o + r
+
+    def reset(self, run_id: str):
+        with self._lock:
+            self._windows.pop(run_id, None)
+            self._last_model.pop(run_id, None)
+
+
 token_meter = TokenMeter()  # 单例

package/app/core/tool_outputs.py

@@ -1,107 +1,107 @@
-# -*- coding: utf-8 -*-
-"""Bounded, run-scoped storage for large tool results omitted from model context."""
-from __future__ import annotations
-
-import hashlib
-import os
-import re
-import stat
-from pathlib import Path
-
-from . import paths
-
-_DIR = paths.DATA_DIR / "tool_outputs"
-_REF_RE = re.compile(r"^[a-f0-9]{32}$")
-MAX_RESULT_BYTES = 4 * 1024 * 1024
-MAX_RUN_BYTES = 32 * 1024 * 1024
-MAX_READ_CHARS = 20000
-
-
-def _run_dir(run_id):
-    return _DIR / hashlib.sha256(str(run_id or "").encode("utf-8")).hexdigest()
-
-
-def save(run_id, call_id, content):
-    """Store one output and return an opaque reference, or empty string on limits/errors."""
-    if not str(run_id or "").strip():
-        return ""
-    raw = str(content or "").encode("utf-8", errors="replace")
-    if len(raw) > MAX_RESULT_BYTES:
-        return ""
-    run_dir = _run_dir(run_id)
-    ref = hashlib.sha256((str(call_id or "") + "\0").encode("utf-8") + raw).hexdigest()[:32]
-    try:
-        _DIR.mkdir(parents=True, exist_ok=True)
-        run_dir.mkdir(mode=0o700, exist_ok=True)
-        if run_dir.is_symlink() or (hasattr(run_dir, "is_junction") and run_dir.is_junction()):
-            return ""
-        target = run_dir / (ref + ".txt")
-        if target.exists():
-            return ref if target.is_file() and not target.is_symlink() else ""
-        total = sum(p.stat().st_size for p in run_dir.glob("*.txt") if p.is_file())
-        if total + len(raw) > MAX_RUN_BYTES:
-            return ""
-        flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL
-        flags |= getattr(os, "O_NOFOLLOW", 0)
-        fd = os.open(str(target), flags, 0o600)
-        try:
-            if not stat.S_ISREG(os.fstat(fd).st_mode):
-                return ""
-            with os.fdopen(fd, "wb", closefd=False) as handle:
-                handle.write(raw)
-                handle.flush()
-        finally:
-            os.close(fd)
-        return ref
-    except (OSError, ValueError):
-        return ""
-
-
-def read(run_id, ref, *, offset=0, limit=MAX_READ_CHARS):
-    """Read a bounded slice, scoped to a single run and an opaque content reference."""
-    if not str(run_id or "").strip() or not _REF_RE.fullmatch(str(ref or "")):
-        return {"ok": False, "error": "工具结果引用无效"}
-    run_dir = _run_dir(run_id)
-    if run_dir.is_symlink() or (hasattr(run_dir, "is_junction") and run_dir.is_junction()):
-        return {"ok": False, "error": "工具结果存储路径不安全"}
-    target = run_dir / (str(ref) + ".txt")
-    if target.is_symlink() or (hasattr(target, "is_junction") and target.is_junction()):
-        return {"ok": False, "error": "工具结果存储路径不安全"}
-    try:
-        offset = max(0, int(offset or 0))
-        limit = max(1, min(MAX_READ_CHARS, int(limit or MAX_READ_CHARS)))
-        with target.open("rb") as handle:
-            handle.seek(offset)
-            raw = handle.read(limit * 4 + 4)
-            text = raw.decode("utf-8", errors="replace")[:limit]
-            end = handle.tell()
-            handle.seek(0, os.SEEK_END)
-            size = handle.tell()
-        return {"ok": True, "text": text, "offset": offset,
-                "next_offset": end if end < size else None, "size_bytes": size}
-    except (OSError, ValueError, TypeError):
-        return {"ok": False, "error": "找不到此运行中的工具结果引用"}
-
-
-def matches_compacted_output(run_id, call_id, ref, head, tail):
-    """Verify a compacted preview belongs to this call and stored full output."""
-    if not str(run_id or "").strip() or not _REF_RE.fullmatch(str(ref or "")):
-        return False
-    run_dir = _run_dir(run_id)
-    if run_dir.is_symlink() or (hasattr(run_dir, "is_junction") and run_dir.is_junction()):
-        return False
-    target = run_dir / (str(ref) + ".txt")
-    if target.is_symlink() or (hasattr(target, "is_junction") and target.is_junction()):
-        return False
-    try:
-        if target.stat().st_size > MAX_RESULT_BYTES:
-            return False
-        raw = target.read_bytes()
-        expected_ref = hashlib.sha256(
-            (str(call_id or "") + "\0").encode("utf-8") + raw).hexdigest()[:32]
-        if expected_ref != ref:
-            return False
-        return (raw.startswith(str(head or "").encode("utf-8", errors="replace"))
-                and raw.endswith(str(tail or "").encode("utf-8", errors="replace")))
-    except (OSError, ValueError):
-        return False
+# -*- coding: utf-8 -*-
+"""Bounded, run-scoped storage for large tool results omitted from model context."""
+from __future__ import annotations
+
+import hashlib
+import os
+import re
+import stat
+from pathlib import Path
+
+from . import paths
+
+_DIR = paths.DATA_DIR / "tool_outputs"
+_REF_RE = re.compile(r"^[a-f0-9]{32}$")
+MAX_RESULT_BYTES = 4 * 1024 * 1024
+MAX_RUN_BYTES = 32 * 1024 * 1024
+MAX_READ_CHARS = 20000
+
+
+def _run_dir(run_id):
+    return _DIR / hashlib.sha256(str(run_id or "").encode("utf-8")).hexdigest()
+
+
+def save(run_id, call_id, content):
+    """Store one output and return an opaque reference, or empty string on limits/errors."""
+    if not str(run_id or "").strip():
+        return ""
+    raw = str(content or "").encode("utf-8", errors="replace")
+    if len(raw) > MAX_RESULT_BYTES:
+        return ""
+    run_dir = _run_dir(run_id)
+    ref = hashlib.sha256((str(call_id or "") + "\0").encode("utf-8") + raw).hexdigest()[:32]
+    try:
+        _DIR.mkdir(parents=True, exist_ok=True)
+        run_dir.mkdir(mode=0o700, exist_ok=True)
+        if run_dir.is_symlink() or (hasattr(run_dir, "is_junction") and run_dir.is_junction()):
+            return ""
+        target = run_dir / (ref + ".txt")
+        if target.exists():
+            return ref if target.is_file() and not target.is_symlink() else ""
+        total = sum(p.stat().st_size for p in run_dir.glob("*.txt") if p.is_file())
+        if total + len(raw) > MAX_RUN_BYTES:
+            return ""
+        flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL
+        flags |= getattr(os, "O_NOFOLLOW", 0)
+        fd = os.open(str(target), flags, 0o600)
+        try:
+            if not stat.S_ISREG(os.fstat(fd).st_mode):
+                return ""
+            with os.fdopen(fd, "wb", closefd=False) as handle:
+                handle.write(raw)
+                handle.flush()
+        finally:
+            os.close(fd)
+        return ref
+    except (OSError, ValueError):
+        return ""
+
+
+def read(run_id, ref, *, offset=0, limit=MAX_READ_CHARS):
+    """Read a bounded slice, scoped to a single run and an opaque content reference."""
+    if not str(run_id or "").strip() or not _REF_RE.fullmatch(str(ref or "")):
+        return {"ok": False, "error": "工具结果引用无效"}
+    run_dir = _run_dir(run_id)
+    if run_dir.is_symlink() or (hasattr(run_dir, "is_junction") and run_dir.is_junction()):
+        return {"ok": False, "error": "工具结果存储路径不安全"}
+    target = run_dir / (str(ref) + ".txt")
+    if target.is_symlink() or (hasattr(target, "is_junction") and target.is_junction()):
+        return {"ok": False, "error": "工具结果存储路径不安全"}
+    try:
+        offset = max(0, int(offset or 0))
+        limit = max(1, min(MAX_READ_CHARS, int(limit or MAX_READ_CHARS)))
+        with target.open("rb") as handle:
+            handle.seek(offset)
+            raw = handle.read(limit * 4 + 4)
+            text = raw.decode("utf-8", errors="replace")[:limit]
+            end = handle.tell()
+            handle.seek(0, os.SEEK_END)
+            size = handle.tell()
+        return {"ok": True, "text": text, "offset": offset,
+                "next_offset": end if end < size else None, "size_bytes": size}
+    except (OSError, ValueError, TypeError):
+        return {"ok": False, "error": "找不到此运行中的工具结果引用"}
+
+
+def matches_compacted_output(run_id, call_id, ref, head, tail):
+    """Verify a compacted preview belongs to this call and stored full output."""
+    if not str(run_id or "").strip() or not _REF_RE.fullmatch(str(ref or "")):
+        return False
+    run_dir = _run_dir(run_id)
+    if run_dir.is_symlink() or (hasattr(run_dir, "is_junction") and run_dir.is_junction()):
+        return False
+    target = run_dir / (str(ref) + ".txt")
+    if target.is_symlink() or (hasattr(target, "is_junction") and target.is_junction()):
+        return False
+    try:
+        if target.stat().st_size > MAX_RESULT_BYTES:
+            return False
+        raw = target.read_bytes()
+        expected_ref = hashlib.sha256(
+            (str(call_id or "") + "\0").encode("utf-8") + raw).hexdigest()[:32]
+        if expected_ref != ref:
+            return False
+        return (raw.startswith(str(head or "").encode("utf-8", errors="replace"))
+                and raw.endswith(str(tail or "").encode("utf-8", errors="replace")))
+    except (OSError, ValueError):
+        return False