webbee 0.4.4__tar.gz → 0.5.1__tar.gz

{webbee-0.4.4 → webbee-0.5.1}/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.5.1
+
+**Security fixes for the remote and local code sync.**
+
+* The system-`sftp` fallback refuses a remote path with a control character: a file name from a server can
+  no longer start a second batch command (sftp's `!` runs a local shell).
+* The local sync never reads a symlink or a path that resolves outside the workspace.
+
+## 0.5.0
+
+**Webbee v0.5.0: one code graph for every source.**
+
+* **The code index feeds the Tenant Vault**: the workspace's files, definitions and links go into the vault's
+  code graph, so the panel, Telegram and the kernel answer code questions about your repos from the same graph.
+* **`intel_sync_remote`**: a repo on a server you reach with your own `ssh` is synced over SFTP (no remote
+  commands, nothing written, symlinks never followed, never a password prompt) -- code questions about it are
+  answered from the vault; a key that needs interactive login is said plainly.
+* **Shared extractor**: parsing, chunks and embeddings come from `imperal-sdk` (`imperal_sdk.code_index`, >= 6.3.2).
+* Requires `asyncssh` for direct SFTP (falls back to the system `sftp` through an open master connection).
+
 ## 0.4.4
 
 **Webbee v0.4.4: Clean Tool Rendering, Real-Time Action Cost Estimation & Terminal Robustness.**

{webbee-0.4.4 → webbee-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: webbee
-Version: 0.4.4
+Version: 0.5.1
 Summary: Webbee 🐝 — the Imperal Cloud coding agent in your terminal
 Project-URL: Homepage, https://imperal.io
 Project-URL: Documentation, https://docs.imperal.io
@@ -25,10 +25,11 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development
 Classifier: Topic :: Utilities
 Requires-Python: >=3.9
+Requires-Dist: asyncssh>=2.14
 Requires-Dist: httpx-sse>=0.4
 Requires-Dist: httpx>=0.27
 Requires-Dist: imperal-mcp>=0.5.0
-Requires-Dist: imperal-sdk>=5.9.3
+Requires-Dist: imperal-sdk>=6.3.2
 Requires-Dist: model2vec>=0.8.2; sys_platform != 'darwin' or platform_machine != 'x86_64' or python_version < '3.13'
 Requires-Dist: numpy>=2; sys_platform != 'darwin' or platform_machine != 'x86_64' or python_version < '3.13'
 Requires-Dist: prompt-toolkit>=3

{webbee-0.4.4 → webbee-0.5.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "webbee"
-version = "0.4.4"
+version = "0.5.1"
 description = "Webbee 🐝 — the Imperal Cloud coding agent in your terminal"
 readme = "README.md"
 license = "GPL-3.0-or-later"
@@ -9,7 +9,8 @@ requires-python = ">=3.9"
 authors = [{ name = "Imperal, Inc.", email = "hello@imperal.io" }]
 dependencies = [
     "imperal-mcp>=0.5.0",
-    "imperal-sdk>=5.9.3",
+    "imperal-sdk>=6.3.2",
+    "asyncssh>=2.14",
     "httpx>=0.27",
     "httpx-sse>=0.4",
     "rich>=13.7",

webbee-0.5.1/src/webbee/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.5.1"

webbee-0.5.1/src/webbee/browser.py

@@ -0,0 +1,261 @@
+"""inspect_page: look at a web page in the local browser over the Chrome DevTools Protocol.
+
+One call returns what the kernel needs to MEASURE a screen (truth-loop stage 10): per viewport
+width, the visible element boxes with their roles, text, z-index and computed colors (the painted
+background behind each, not a guess), the page's scroll width, and one screenshot. The agent no
+longer writes its own websocket scripts against port 9222 (live: 56 of 205 shell calls of one
+UI task were such scripts).
+
+Stdlib only: a minimal RFC 6455 client (text frames, client masking, ping/pong) -- no new
+dependency for a verb most sessions never call.
+"""
+from __future__ import annotations
+
+import base64
+import json
+import os
+import socket
+import struct
+import time
+import urllib.parse
+import urllib.request
+
+DEFAULT_PORT = 9222
+DEFAULT_WIDTHS = (375, 768, 1440)
+VIEW_HEIGHT = 900
+MAX_ELEMENTS = 400
+_TIMEOUT = 20.0
+
+# the page side: visible boxes worth measuring, in page coordinates, with the painted background
+_COLLECT_JS = r"""
+(() => {
+  const MAX = %d;
+  const vw = window.innerWidth, vh = window.innerHeight;
+  const sx = window.scrollX, sy = window.scrollY;
+  const IMPLICIT = {A: 'link', BUTTON: 'button', INPUT: 'input', SELECT: 'select', TEXTAREA: 'textbox',
+                    H1: 'h1', H2: 'h2', H3: 'h3', IMG: 'img', NAV: 'navigation', HEADER: 'banner',
+                    FOOTER: 'contentinfo', MAIN: 'main', LABEL: 'label', P: 'text', LI: 'listitem'};
+  const painted = (el) => {
+    for (let e = el; e && e.nodeType === 1; e = e.parentElement) {
+      const c = getComputedStyle(e).backgroundColor;
+      if (c && c !== 'transparent' && !/rgba\([^)]*,\s*0\)$/.test(c)) return c;
+    }
+    return 'rgb(255, 255, 255)';
+  };
+  const ownText = (el) => Array.from(el.childNodes).filter(n => n.nodeType === 3)
+                              .map(n => n.textContent).join(' ').replace(/\s+/g, ' ').trim();
+  const out = [];
+  const all = document.body ? document.body.querySelectorAll('*') : [];
+  for (const el of all) {
+    if (out.length >= MAX) break;
+    const r = el.getBoundingClientRect();
+    if (r.width < 1 || r.height < 1) continue;
+    const cs = getComputedStyle(el);
+    if (cs.visibility === 'hidden' || cs.display === 'none' || parseFloat(cs.opacity) === 0) continue;
+    const role = (el.getAttribute('role') || IMPLICIT[el.tagName] || '').toLowerCase();
+    const text = ownText(el);
+    const handlers = !!(el.onclick || el.getAttribute('onclick') || cs.cursor === 'pointer');
+    if (!role && !text && !handlers) continue;
+    out.push({
+      id: el.id || (el.getAttribute('data-testid') || '') || (el.tagName.toLowerCase() + '_' + out.length),
+      tag: el.tagName.toLowerCase(), role: role, text: (text || el.getAttribute('aria-label') || el.alt || '').slice(0, 100),
+      x: Math.round(r.left + sx), y: Math.round(r.top + sy), w: Math.round(r.width), h: Math.round(r.height),
+      z_index: parseInt(cs.zIndex) || 0, color: cs.color, background: painted(el),
+      font_size: parseFloat(cs.fontSize) || 0, font_weight: parseInt(cs.fontWeight) || 400,
+      has_handlers: handlers,
+    });
+  }
+  return JSON.stringify({width: vw, height: vh, scroll_width: document.documentElement.scrollWidth,
+                         title: document.title, url: location.href, elements: out});
+})()
+""" % MAX_ELEMENTS
+
+
+class CDPError(Exception):
+    pass
+
+
+class _WebSocket:
+    """A minimal websocket client: enough for CDP (text frames in, text frames out)."""
+
+    def __init__(self, url: str, timeout: float = _TIMEOUT):
+        u = urllib.parse.urlparse(url)
+        self.sock = socket.create_connection((u.hostname, u.port or 80), timeout=timeout)
+        key = base64.b64encode(os.urandom(16)).decode()
+        path = u.path + (f"?{u.query}" if u.query else "")
+        self.sock.sendall((f"GET {path} HTTP/1.1\r\nHost: {u.hostname}:{u.port}\r\nUpgrade: websocket\r\n"
+                           f"Connection: Upgrade\r\nSec-WebSocket-Key: {key}\r\nSec-WebSocket-Version: 13\r\n\r\n")
+                          .encode())
+        head = b""
+        while b"\r\n\r\n" not in head:
+            chunk = self.sock.recv(4096)
+            if not chunk:
+                raise CDPError("the browser closed the connection during the handshake")
+            head += chunk
+        status = head.split(b"\r\n", 1)[0].decode(errors="replace")
+        if " 101 " not in status:
+            raise CDPError(f"websocket handshake refused: {status}")
+        self.buf = head.split(b"\r\n\r\n", 1)[1]
+
+    def _recv_exact(self, n: int) -> bytes:
+        while len(self.buf) < n:
+            chunk = self.sock.recv(max(65536, n - len(self.buf)))
+            if not chunk:
+                raise CDPError("the browser closed the connection")
+            self.buf += chunk
+        out, self.buf = self.buf[:n], self.buf[n:]
+        return out
+
+    def send(self, text: str) -> None:
+        data = text.encode()
+        head = bytearray([0x81])
+        n = len(data)
+        if n < 126:
+            head.append(0x80 | n)
+        elif n < 65536:
+            head += bytes([0x80 | 126]) + struct.pack(">H", n)
+        else:
+            head += bytes([0x80 | 127]) + struct.pack(">Q", n)
+        mask = os.urandom(4)
+        self.sock.sendall(bytes(head) + mask + bytes(b ^ mask[i % 4] for i, b in enumerate(data)))
+
+    def _send_control(self, opcode: int, payload: bytes = b"") -> None:
+        mask = os.urandom(4)
+        self.sock.sendall(bytes([0x80 | opcode, 0x80 | len(payload)]) + mask
+                          + bytes(b ^ mask[i % 4] for i, b in enumerate(payload)))
+
+    def recv(self) -> str:
+        parts = []
+        while True:
+            b1, b2 = self._recv_exact(2)
+            opcode, n = b1 & 0x0F, b2 & 0x7F
+            if n == 126:
+                n = struct.unpack(">H", self._recv_exact(2))[0]
+            elif n == 127:
+                n = struct.unpack(">Q", self._recv_exact(8))[0]
+            mask = self._recv_exact(4) if b2 & 0x80 else b""
+            data = self._recv_exact(n)
+            if mask:
+                data = bytes(b ^ mask[i % 4] for i, b in enumerate(data))
+            if opcode == 0x9:
+                self._send_control(0xA, data)
+                continue
+            if opcode == 0x8:
+                raise CDPError("the browser closed the page connection")
+            if opcode in (0x1, 0x2, 0x0):
+                parts.append(data)
+                if b1 & 0x80:
+                    return b"".join(parts).decode(errors="replace")
+
+    def close(self) -> None:
+        try:
+            self._send_control(0x8)
+            self.sock.close()
+        except OSError:
+            pass
+
+
+class _Page:
+    def __init__(self, ws_url: str):
+        self.ws = _WebSocket(ws_url)
+        self.n = 0
+
+    def call(self, method: str, params: dict | None = None, timeout: float = _TIMEOUT) -> dict:
+        self.n += 1
+        mid = self.n
+        self.ws.send(json.dumps({"id": mid, "method": method, "params": params or {}}))
+        end = time.monotonic() + timeout
+        while time.monotonic() < end:
+            msg = json.loads(self.ws.recv())
+            if msg.get("id") == mid:
+                if "error" in msg:
+                    raise CDPError(f"{method}: {msg['error'].get('message')}")
+                return msg.get("result") or {}
+        raise CDPError(f"{method}: no answer in {timeout:.0f}s")
+
+    def evaluate(self, expr: str):
+        res = self.call("Runtime.evaluate", {"expression": expr, "returnByValue": True, "awaitPromise": True})
+        if res.get("exceptionDetails"):
+            raise CDPError(f"page script failed: {res['exceptionDetails'].get('text')}")
+        return (res.get("result") or {}).get("value")
+
+    def wait_loaded(self, timeout: float = 15.0) -> None:
+        end = time.monotonic() + timeout
+        while time.monotonic() < end:
+            if self.evaluate("document.readyState") == "complete":
+                return
+            time.sleep(0.25)
+
+
+def _http_json(port: int, path: str, method: str = "GET"):
+    req = urllib.request.Request(f"http://127.0.0.1:{port}{path}", method=method)
+    with urllib.request.urlopen(req, timeout=5) as r:
+        return json.loads(r.read().decode() or "null")
+
+
+def _pick_tab(port: int, url: str, tab: str) -> dict:
+    tabs = [t for t in _http_json(port, "/json/list") or [] if t.get("type") == "page"]
+    if tab:
+        for t in tabs:
+            if tab in (t.get("id"), ) or tab in str(t.get("url") or "") or tab in str(t.get("title") or ""):
+                return t
+        raise CDPError(f"no open tab matches {tab!r} (open: {', '.join(str(t.get('url'))[:60] for t in tabs[:8])})")
+    if url:
+        for t in tabs:
+            if str(t.get("url") or "").rstrip("/") == url.rstrip("/"):
+                return t
+        quoted = urllib.parse.quote(url, safe=":/?&=#%")
+        try:
+            return _http_json(port, f"/json/new?{quoted}", method="PUT")
+        except Exception:
+            return _http_json(port, f"/json/new?{quoted}")
+    if not tabs:
+        raise CDPError("the browser has no open page; pass url")
+    return tabs[0]
+
+
+def inspect_page(url: str = "", tab: str = "", widths=None, screenshot: bool = True,
+                 port: int = DEFAULT_PORT) -> dict:
+    """The page's boxes per width and one screenshot (at the widest width), or ``ok: False`` with why."""
+    widths = [int(w) for w in (widths or DEFAULT_WIDTHS) if 200 <= int(w) <= 4000][:5] or list(DEFAULT_WIDTHS)
+    try:
+        target = _pick_tab(port, url, tab)
+    except (OSError, ValueError) as e:
+        return {"ok": False, "content": f"inspect_page: no browser with remote debugging on port {port} ({e}). "
+                                        f"Start Chrome/Brave with --remote-debugging-port={port}."}
+    except CDPError as e:
+        return {"ok": False, "content": f"inspect_page: {e}"}
+    page = None
+    try:
+        page = _Page(target["webSocketDebuggerUrl"])
+        page.call("Page.enable")
+        if url and str(target.get("url") or "").rstrip("/") != url.rstrip("/"):
+            page.call("Page.navigate", {"url": url})
+        elif url:
+            page.call("Page.reload", {"ignoreCache": True})
+        page.wait_loaded()
+        viewports, title, href = [], "", url
+        for w in widths:
+            page.call("Emulation.setDeviceMetricsOverride",
+                      {"width": w, "height": VIEW_HEIGHT, "deviceScaleFactor": 1, "mobile": w < 768})
+            time.sleep(0.4)          # layout settles (media queries, transitions)
+            got = json.loads(page.evaluate(_COLLECT_JS) or "{}")
+            viewports.append({"width": w, "height": got.get("height") or VIEW_HEIGHT,
+                              "scroll_width": got.get("scroll_width"), "elements": got.get("elements") or []})
+            title, href = got.get("title") or "", got.get("url") or url
+        png = ""
+        if screenshot:
+            shot = page.call("Page.captureScreenshot", {"format": "jpeg", "quality": 60})
+            png = "data:image/jpeg;base64," + str(shot.get("data") or "") if shot.get("data") else ""
+        page.call("Emulation.clearDeviceMetricsOverride")
+    except (CDPError, OSError, ValueError, KeyError) as e:
+        return {"ok": False, "content": f"inspect_page: {e}"}
+    finally:
+        if page is not None:
+            page.ws.close()
+    summary = "; ".join(f"{v['width']}px: {len(v['elements'])} boxes"
+                        + (f", page {v['scroll_width']}px wide" if (v.get("scroll_width") or 0) > v["width"] else "")
+                        for v in viewports)
+    return {"ok": True, "content": f"inspect_page {href}: {summary}"
+                                   + (f"; screenshot at {widths[-1]}px" if png else ""),
+            "url": href, "title": title, "viewports": viewports, "png_base64": png}

{webbee-0.4.4 → webbee-0.5.1}/src/webbee/consent.py

@@ -10,6 +10,12 @@ from dataclasses import dataclass
 from webbee.frames import _is_foreign_frame, render_foreign_frame
 
 
+# Verbs that only read: the kernel never asks consent for them (a verified read, core.action_effect); a
+# confirm_request naming one is answered yes here without a prompt (code graph spec §4.8: index reads
+# never ask -- intel_sync_remote lists and reads a repo over SFTP, writes nothing, runs nothing there).
+READ_VERBS = frozenset({"intel_sync_remote"})
+
+
 async def handle_confirm_request(frame: dict, mode: str, ask_consent) -> dict:
     """ICNLI consent path. The client does NOT interpret consent words — it
     relays the user's RAW reply; the kernel brain interprets intent
@@ -17,7 +23,7 @@ async def handle_confirm_request(frame: dict, mode: str, ask_consent) -> dict:
     `ask_consent(app_id, tool, args)` is an async coroutine returning the raw
     reply (resolved through the pinned dock, or a sync fallback reader)."""
     req_id = frame["req_id"]
-    if mode == "autopilot":
+    if mode == "autopilot" or (not frame.get("app_id") and frame.get("tool") in READ_VERBS):
         return {"req_id": req_id, "result": {"approved": True}}
     if mode == "plan":
         return {"req_id": req_id, "result": {"approved": False, "reason": "plan_mode"}}

{webbee-0.4.4 → webbee-0.5.1}/src/webbee/intel/graph.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 from collections import defaultdict
 
-from webbee.intel.models import ProjectIndex, Symbol
+from imperal_sdk.code_index import ProjectIndex, Symbol
 
 
 class CodeGraph:

webbee-0.5.1/src/webbee/intel/outline.py

@@ -0,0 +1,248 @@
+"""A code file read by meaning, not by windows (CPC ``outline`` / ``read_symbol``).
+
+The same tree-sitter packages as the index (``indexer.py``) give, for one file:
+- ``outline``: the definitions AND the significant nodes inside them with line ranges --
+  a big assignment (``security_content = Stack(``), a big keyword argument or object
+  property, a big returned tree, a comment header. For a declarative UI file this is its map;
+- ``read_symbol``: exactly one such node, whole (in the read_file card form);
+- ``syntax_errors``: the first ERROR / MISSING nodes.
+
+Kept in step with the kernel's ``imperal_kernel/core/code_outline.py`` (it parses remote
+files the same way). Fail-soft: no parser -> None, never a crash."""
+from __future__ import annotations
+
+import os
+import re
+from typing import Any, Dict, List, Optional, Tuple
+
+LANG_BY_EXT = {".py": "python", ".ts": "typescript", ".tsx": "tsx", ".js": "javascript", ".jsx": "javascript",
+               ".mjs": "javascript", ".cjs": "javascript"}
+BIG_LINES = 12            # an inner node this long is a region of the file worth naming
+MAX_NODES = 400           # one outline never floods a frame
+_HEADER = re.compile(r"^\s*(?:#|//|/\*+)\s*(?:[=\-#*─—_~]{3,}\s*)?([^=\-#*─—_~\s][^\n]*?)\s*(?:[=\-#*─—_~]{3,})?\s*(?:\*/)?$")
+_RULE = re.compile(r"^\s*(?:#|//|/\*+)\s*[=\-#*─—_~]{3,}")
+
+_DEF_NODES = {
+    "python": {"function_definition": "function", "class_definition": "class"},
+    "typescript": {"function_declaration": "function", "class_declaration": "class", "method_definition": "method",
+                   "interface_declaration": "class", "type_alias_declaration": "type", "enum_declaration": "class"},
+    "javascript": {"function_declaration": "function", "class_declaration": "class", "method_definition": "method"},
+}
+_DEF_NODES["tsx"] = _DEF_NODES["typescript"]
+# inner nodes that name a region: (node type -> the field that holds its name)
+_REGION_NODES = {
+    "python": {"assignment": "left", "keyword_argument": "name", "pair": "key", "decorated_definition": ""},
+    "typescript": {"variable_declarator": "name", "pair": "key", "assignment_expression": "left",
+                   "public_field_definition": "name"},
+    "javascript": {"variable_declarator": "name", "pair": "key", "assignment_expression": "left",
+                   "field_definition": "property"},
+}
+_REGION_NODES["tsx"] = _REGION_NODES["typescript"]
+_FUNCTION_VALUES = {"arrow_function", "function_expression", "function", "lambda"}
+_LANG_CACHE: Dict[str, Any] = {}
+
+
+def lang_of(path: str) -> str:
+    return LANG_BY_EXT.get(os.path.splitext(str(path or ""))[1].lower(), "")
+
+
+def _language(lang: str):
+    if lang in _LANG_CACHE:
+        return _LANG_CACHE[lang]
+    try:
+        from tree_sitter import Language
+        if lang == "python":
+            import tree_sitter_python as m
+            obj = Language(m.language())
+        elif lang in ("typescript", "tsx"):
+            import tree_sitter_typescript as m
+            obj = Language(m.language_tsx() if lang == "tsx" else m.language_typescript())
+        elif lang == "javascript":
+            import tree_sitter_javascript as m
+            obj = Language(m.language())
+        else:
+            obj = None
+    except Exception:
+        obj = None
+    _LANG_CACHE[lang] = obj
+    return obj
+
+
+def parse(path: str, text: str):
+    """``(tree, source bytes, lang)``, or None when the file is not code the parser knows."""
+    lang = lang_of(path)
+    language = _language(lang) if lang else None
+    if language is None:
+        return None
+    from tree_sitter import Parser
+    src = str(text or "").encode("utf-8", "replace")
+    return Parser(language).parse(src), src, lang
+
+
+def _text(src: bytes, node) -> str:
+    return src[node.start_byte:node.end_byte].decode("utf-8", "replace")
+
+
+def _first_line(src: bytes, node, n: int = 80) -> str:
+    return " ".join(_text(src, node).split("\n", 1)[0].split())[:n]
+
+
+def _lines(node) -> Tuple[int, int]:
+    return node.start_point[0] + 1, node.end_point[0] + 1
+
+
+def _value_of(node):
+    for f in ("right", "value"):
+        v = node.child_by_field_name(f)
+        if v is not None:
+            return v
+    return None
+
+
+def _callee(src: bytes, value) -> str:
+    """What a region holds, in a few words: ``Stack(``, ``<Dialog>``, ``[...]``."""
+    if value is None:
+        return ""
+    if value.type in ("call", "call_expression", "new_expression"):
+        fn = value.child_by_field_name("function") or value.child_by_field_name("constructor")
+        return (_first_line(src, fn, 60) if fn is not None else "") + "("
+    if value.type in ("jsx_element", "jsx_self_closing_element", "parenthesized_expression"):
+        return "<" + _first_line(src, value, 60).lstrip("(<").split(" ", 1)[0].split(">", 1)[0] + ">"
+    if value.type in ("list", "array"):
+        return "[...]"
+    if value.type in ("dictionary", "object"):
+        return "{...}"
+    return ""
+
+
+def outline(path: str, text: str) -> Optional[List[Dict[str, Any]]]:
+    """The file's map: ``[{name, kind, start, end, depth}]`` in line order (definitions, their big
+    inner regions, comment headers). None when the file is not code the parser knows."""
+    parsed = parse(path, text)
+    if parsed is None:
+        return None
+    tree, src, lang = parsed
+    defs, regions = _DEF_NODES.get(lang, {}), _REGION_NODES.get(lang, {})
+    out: List[Dict[str, Any]] = []
+
+    def add(name: str, kind: str, node, depth: int) -> None:
+        a, b = _lines(node)
+        out.append({"name": name, "kind": kind, "start": a, "end": b, "depth": depth})
+
+    stack = [(tree.root_node, 0, "", 0)]
+    while stack:
+        node, depth, owner, nest = stack.pop()     # nest: regions this node sits in
+        kind = defs.get(node.type)
+        child_depth, child_owner, child_nest = depth, owner, nest
+        if kind:
+            nm = node.child_by_field_name("name")
+            name = _text(src, nm) if nm is not None else _first_line(src, node, 40)
+            full = f"{owner}.{name}" if owner else name
+            add(full, kind, node, depth)
+            child_depth, child_owner, child_nest = depth + 1, full, 0
+        elif node.type in regions and node.type != "decorated_definition":
+            field = regions[node.type]
+            nm = node.child_by_field_name(field) if field else None
+            value = _value_of(node)
+            a, b = _lines(node)
+            if nm is not None and value is not None and value.type in _FUNCTION_VALUES and lang != "python":
+                full = f"{owner}.{_text(src, nm)}" if owner else _text(src, nm)
+                add(full, "function", node, depth)          # const Component = () => ...
+                child_depth, child_owner, child_nest = depth + 1, full, 0
+            elif nm is not None and b - a + 1 >= BIG_LINES * (1 + 2 * nest):
+                # a region inside a region is named only when it is a large part of it
+                label = " ".join(_text(src, nm).split())[:60]
+                what = _callee(src, value)
+                add(f"{owner}.{label}" if owner else label, "region", node, depth)
+                out[-1]["holds"] = what
+                child_depth, child_nest = depth + 1, nest + 1
+        elif node.type in ("return_statement",) and owner:
+            a, b = _lines(node)
+            value = node.named_children[0] if node.named_children else None
+            if value is not None and b - a + 1 >= BIG_LINES:
+                add(f"{owner}.return", "region", node, depth)
+                out[-1]["holds"] = _callee(src, value)
+        elif node.type == "comment":
+            line = _text(src, node).split("\n", 1)[0]
+            prev = node.prev_sibling
+            ruled = bool(_RULE.match(line)) or (prev is not None and prev.type == "comment"
+                                               and bool(_RULE.match(_text(src, prev))))
+            m = _HEADER.match(line)
+            if ruled and m and m.group(1).strip() and not _RULE.fullmatch(line.strip()):
+                add(m.group(1).strip()[:80], "section", node, depth)
+        for ch in reversed(node.children):
+            stack.append((ch, child_depth, child_owner, child_nest))
+    out.sort(key=lambda d: (d["start"], d["depth"]))
+    return out[:MAX_NODES]
+
+
+def render_outline(path: str, nodes: List[Dict[str, Any]], total_lines: int) -> str:
+    """The outline as the model reads it: one line per node, indented by depth."""
+    head = f"OUTLINE of {path} ({total_lines} lines; read a part whole with read_symbol(path, name), "\
+           "or read_file with offset/limit):"
+    rows = [f"{'  ' * int(n['depth'])}{n['start']}-{n['end']} {n['kind']} {n['name']}"
+            + (f" = {n['holds']}" if n.get("holds") else "") for n in nodes]
+    return "\n".join([head] + rows)
+
+
+_RANGE = re.compile(r"^L?(\d+)\s*[-:]\s*L?(\d+)$")
+
+
+def find_symbol(nodes: List[Dict[str, Any]], name: str) -> Optional[Dict[str, Any]]:
+    """The outline node ``name`` names: an exact full name, then the last dotted part, then case-blind."""
+    want = str(name or "").strip()
+    if not want:
+        return None
+    m = _RANGE.match(want)
+    if m:
+        return {"name": want, "kind": "lines", "start": int(m.group(1)), "end": int(m.group(2)), "depth": 0}
+    for pick in (lambda n: n["name"] == want,
+                 lambda n: n["name"].rsplit(".", 1)[-1] == want,
+                 lambda n: n["name"].lower() == want.lower() or n["name"].rsplit(".", 1)[-1].lower() == want.lower()):
+        hit = next((n for n in nodes if pick(n)), None)
+        if hit is not None:
+            return hit
+    return None
+
+
+def read_symbol(path: str, text: str, name: str) -> Optional[Dict[str, Any]]:
+    """``{name, kind, start, end, body}`` of one node, whole -- in the shape of a read_file
+    window, so the kernel remembers it as the file's exact lines. None when not found."""
+    nodes = outline(path, text) or []
+    hit = find_symbol(nodes, name)
+    if hit is None:
+        return None
+    lines = str(text or "").split("\n")
+    a, b = max(1, hit["start"]), min(len(lines), hit["end"])
+    return {**hit, "start": a, "end": b, "body": "\n".join(lines[a - 1:b])}
+
+
+def read_card(path: str, total_lines: int, a: int, b: int, body: str) -> str:
+    """A part of a file in the read_file card form (``strip_file_card`` reads it back)."""
+    return f"⟦ {path} · {total_lines} lines ⟧ [showing lines {a}-{b} of {total_lines}]\n{body}"
+
+
+def syntax_errors(path: str, text: str, limit: int = 3) -> Optional[List[Tuple[int, int, str]]]:
+    """The first ERROR / MISSING nodes: ``[(line, column, what)]``; [] when the file parses;
+    None when the file is not code the parser knows."""
+    parsed = parse(path, text)
+    if parsed is None:
+        return None
+    tree, src, _lang = parsed
+    if not tree.root_node.has_error:
+        return []
+    out: List[Tuple[int, int, str]] = []
+    stack = [tree.root_node]
+    while stack and len(out) < limit:
+        node = stack.pop()
+        if node.is_missing:
+            out.append((node.start_point[0] + 1, node.start_point[1] + 1, f"missing {node.type!r}"))
+            continue
+        if node.type == "ERROR":
+            out.append((node.start_point[0] + 1, node.start_point[1] + 1,
+                        f"unexpected {_first_line(src, node, 40)!r}"))
+            continue
+        if node.has_error:
+            stack.extend(reversed(node.children))
+    return sorted(out)
+