catui-agent 1.0.0-beta.0

package/dist/extensions/builtin/browser/src/browser_harness/helpers.py

@@ -0,0 +1,396 @@
+"""Browser control via CDP.
+
+Core helpers live here. Agent-editable helpers live in
+BH_AGENT_WORKSPACE/agent_helpers.py.
+
+[WHO]: Provides Browser Harness navigation, input, screenshot, tab, JavaScript, upload, and HTTP helper functions
+[FROM]: Depends on browser_harness._ipc, CDP daemon requests, urllib, base64, importlib, and optional Pillow
+[TO]: Consumed by browser_harness.run snippets and Catui browser tool calls
+[HERE]: extensions/builtin/browser/src/browser_harness/helpers.py within vendored Browser Harness package
+"""
+import base64, importlib.util, json, math, os, time, urllib.request
+from pathlib import Path
+from urllib.parse import urlparse
+
+from . import _ipc as ipc
+
+
+CORE_DIR = Path(__file__).resolve().parent
+REPO_ROOT = CORE_DIR.parent.parent
+AGENT_WORKSPACE = Path(os.environ.get("BH_AGENT_WORKSPACE", REPO_ROOT / "agent-workspace")).expanduser()
+
+
+def _load_env():
+    paths = [REPO_ROOT / ".env", AGENT_WORKSPACE / ".env"]
+    for p in paths:
+        if not p.exists():
+            continue
+        _load_env_file(p)
+
+
+def _load_env_file(p):
+    for line in p.read_text().splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        k, v = line.split("=", 1)
+        os.environ.setdefault(k.strip(), v.strip().strip('"').strip("'"))
+
+
+_load_env()
+
+NAME = os.environ.get("BU_NAME", "default")
+SOCK = ipc.sock_addr(NAME)
+INTERNAL = ("chrome://", "chrome-untrusted://", "devtools://", "chrome-extension://", "about:")
+
+
+def _send(req):
+    c = ipc.connect(NAME, timeout=5.0)
+    c.sendall((json.dumps(req) + "\n").encode())
+    data = b""
+    while not data.endswith(b"\n"):
+        chunk = c.recv(1 << 20)
+        if not chunk: break
+        data += chunk
+    c.close()
+    r = json.loads(data)
+    if "error" in r: raise RuntimeError(r["error"])
+    return r
+
+
+def cdp(method, session_id=None, **params):
+    """Raw CDP. cdp('Page.navigate', url='...'), cdp('DOM.getDocument', depth=-1)."""
+    return _send({"method": method, "params": params, "session_id": session_id}).get("result", {})
+
+
+def drain_events():  return _send({"meta": "drain_events"})["events"]
+
+
+def _js_snippet(expression, limit=160):
+    snippet = expression.strip().replace("\n", "\\n")
+    return snippet[:limit - 3] + "..." if len(snippet) > limit else snippet
+
+
+def _js_exception_description(result, details):
+    desc = result.get("description")
+    exc = details.get("exception") if details else None
+    if not desc and isinstance(exc, dict):
+        desc = exc.get("description")
+        if desc is None and "value" in exc:
+            desc = str(exc["value"])
+        if desc is None:
+            desc = exc.get("className")
+    if not desc and details:
+        desc = details.get("text")
+    return desc or "JavaScript evaluation failed"
+
+
+def _decode_unserializable_js_value(value):
+    if value == "NaN":
+        return math.nan
+    if value == "Infinity":
+        return math.inf
+    if value == "-Infinity":
+        return -math.inf
+    if value == "-0":
+        return -0.0
+    if value.endswith("n"):
+        return int(value[:-1])
+    return value
+
+
+def _runtime_value(response, expression):
+    result = response.get("result", {})
+    details = response.get("exceptionDetails")
+    if details or result.get("subtype") == "error":
+        desc = _js_exception_description(result, details)
+        if details:
+            line = details.get("lineNumber")
+            col = details.get("columnNumber")
+            loc = f" at line {line}, column {col}" if line is not None and col is not None else ""
+        else:
+            loc = ""
+        raise RuntimeError(f"JavaScript evaluation failed{loc}: {desc}; expression: {_js_snippet(expression)}")
+    if "value" in result:
+        return result["value"]
+    if "unserializableValue" in result:
+        return _decode_unserializable_js_value(result["unserializableValue"])
+    return None
+
+
+def _runtime_evaluate(expression, session_id=None, await_promise=False):
+    try:
+        r = cdp("Runtime.evaluate", session_id=session_id, expression=expression, returnByValue=True, awaitPromise=await_promise)
+    except TimeoutError as e:
+        raise RuntimeError(f"Runtime.evaluate timed out; expression: {_js_snippet(expression)}") from e
+    return _runtime_value(r, expression)
+
+
+def _has_return_statement(expression):
+    i = 0
+    n = len(expression)
+    state = "code"
+    quote = ""
+    while i < n:
+        ch = expression[i]
+        nxt = expression[i + 1] if i + 1 < n else ""
+        if state == "code":
+            if ch in ("'", '"', "`"):
+                state = "string"; quote = ch; i += 1; continue
+            if ch == "/" and nxt == "/":
+                state = "line_comment"; i += 2; continue
+            if ch == "/" and nxt == "*":
+                state = "block_comment"; i += 2; continue
+            if expression.startswith("return", i):
+                before = expression[i - 1] if i > 0 else ""
+                after = expression[i + 6] if i + 6 < n else ""
+                if not (before == "_" or before.isalnum()) and not (after == "_" or after.isalnum()):
+                    return True
+            i += 1; continue
+        if state == "line_comment":
+            if ch == "\n":
+                state = "code"
+            i += 1; continue
+        if state == "block_comment":
+            if ch == "*" and nxt == "/":
+                state = "code"; i += 2; continue
+            i += 1; continue
+        if state == "string":
+            if ch == "\\":
+                i += 2; continue
+            if ch == quote:
+                state = "code"; quote = ""
+            i += 1; continue
+    return False
+
+
+# --- navigation / page ---
+def goto_url(url):
+    r = cdp("Page.navigate", url=url)
+    d = (AGENT_WORKSPACE / "domain-skills" / (urlparse(url).hostname or "").removeprefix("www.").split(".")[0])
+    return {**r, "domain_skills": sorted(p.name for p in d.rglob("*.md"))[:10]} if d.is_dir() else r
+
+def page_info():
+    """{url, title, w, h, sx, sy, pw, ph} — viewport + scroll + page size.
+
+    If a native dialog (alert/confirm/prompt/beforeunload) is open, returns
+    {dialog: {type, message, ...}} instead — the page's JS thread is frozen
+    until the dialog is handled (see interaction-skills/dialogs.md)."""
+    dialog = _send({"meta": "pending_dialog"}).get("dialog")
+    if dialog:
+        return {"dialog": dialog}
+    expression = "JSON.stringify({url:location.href,title:document.title,w:innerWidth,h:innerHeight,sx:scrollX,sy:scrollY,pw:document.documentElement.scrollWidth,ph:document.documentElement.scrollHeight})"
+    return json.loads(_runtime_evaluate(expression))
+
+# --- input ---
+_debug_click_counter = 0
+
+def click_at_xy(x, y, button="left", clicks=1):
+    if os.environ.get("BH_DEBUG_CLICKS"):
+        global _debug_click_counter
+        try:
+            from PIL import Image, ImageDraw
+            dpr = js("window.devicePixelRatio") or 1
+            path = capture_screenshot(str(ipc._TMP / f"debug_click_{_debug_click_counter}.png"))
+            img = Image.open(path)
+            draw = ImageDraw.Draw(img)
+            px, py = int(x * dpr), int(y * dpr)
+            r = int(15 * dpr)
+            draw.ellipse([px - r, py - r, px + r, py + r], outline="red", width=int(3 * dpr))
+            draw.line([px - r - int(5 * dpr), py, px + r + int(5 * dpr), py], fill="red", width=int(2 * dpr))
+            draw.line([px, py - r - int(5 * dpr), px, py + r + int(5 * dpr)], fill="red", width=int(2 * dpr))
+            img.save(path)
+            print(f"[debug_click] saved {path} (x={x}, y={y}, dpr={dpr})")
+        except Exception as e:
+            print(f"[debug_click] overlay failed: {e}")
+        _debug_click_counter += 1
+    cdp("Input.dispatchMouseEvent", type="mousePressed", x=x, y=y, button=button, clickCount=clicks)
+    cdp("Input.dispatchMouseEvent", type="mouseReleased", x=x, y=y, button=button, clickCount=clicks)
+
+def type_text(text):
+    cdp("Input.insertText", text=text)
+
+_KEYS = {  # key → (windowsVirtualKeyCode, code, text)
+    "Enter": (13, "Enter", "\r"), "Tab": (9, "Tab", "\t"), "Backspace": (8, "Backspace", ""),
+    "Escape": (27, "Escape", ""), "Delete": (46, "Delete", ""), " ": (32, "Space", " "),
+    "ArrowLeft": (37, "ArrowLeft", ""), "ArrowUp": (38, "ArrowUp", ""),
+    "ArrowRight": (39, "ArrowRight", ""), "ArrowDown": (40, "ArrowDown", ""),
+    "Home": (36, "Home", ""), "End": (35, "End", ""),
+    "PageUp": (33, "PageUp", ""), "PageDown": (34, "PageDown", ""),
+}
+def press_key(key, modifiers=0):
+    """Modifiers bitfield: 1=Alt, 2=Ctrl, 4=Meta(Cmd), 8=Shift.
+    Special keys (Enter, Tab, Arrow*, Backspace, etc.) carry their virtual key codes
+    so listeners checking e.keyCode / e.key all fire."""
+    vk, code, text = _KEYS.get(key, (ord(key[0]) if len(key) == 1 else 0, key, key if len(key) == 1 else ""))
+    base = {"key": key, "code": code, "modifiers": modifiers, "windowsVirtualKeyCode": vk, "nativeVirtualKeyCode": vk}
+    cdp("Input.dispatchKeyEvent", type="keyDown", **base, **({"text": text} if text else {}))
+    if text and len(text) == 1:
+        cdp("Input.dispatchKeyEvent", type="char", text=text, **{k: v for k, v in base.items() if k != "text"})
+    cdp("Input.dispatchKeyEvent", type="keyUp", **base)
+
+def scroll(x, y, dy=-300, dx=0):
+    cdp("Input.dispatchMouseEvent", type="mouseWheel", x=x, y=y, deltaX=dx, deltaY=dy)
+
+
+# --- visual ---
+def capture_screenshot(path=None, full=False, max_dim=None):
+    """Save a PNG of the current viewport. Set max_dim=1800 on a 2× display to
+    keep the file under the 2000px-per-side limit some image-aware LLMs enforce."""
+    path = path or str(ipc._TMP / "shot.png")
+    r = cdp("Page.captureScreenshot", format="png", captureBeyondViewport=full)
+    open(path, "wb").write(base64.b64decode(r["data"]))
+    if max_dim:
+        from PIL import Image
+        img = Image.open(path)
+        if max(img.size) > max_dim:
+            img.thumbnail((max_dim, max_dim))
+            img.save(path)
+    return path
+
+
+# --- tabs ---
+def list_tabs(include_chrome=True):
+    out = []
+    for t in cdp("Target.getTargets")["targetInfos"]:
+        if t["type"] != "page": continue
+        url = t.get("url", "")
+        if not include_chrome and url.startswith(INTERNAL): continue
+        out.append({"targetId": t["targetId"], "title": t.get("title", ""), "url": url})
+    return out
+
+def current_tab():
+    t = cdp("Target.getTargetInfo").get("targetInfo", {})
+    return {"targetId": t.get("targetId"), "url": t.get("url", ""), "title": t.get("title", "")}
+
+def _mark_tab():
+    """Prepend 🟢 to tab title so the user can see which tab the agent controls."""
+    try: cdp("Runtime.evaluate", expression="if(!document.title.startsWith('\U0001F7E2'))document.title='\U0001F7E2 '+document.title")
+    except Exception: pass
+
+def switch_tab(target):
+    # Accept either a raw targetId string or the dict returned by current_tab() / list_tabs(),
+    # so `switch_tab(current_tab())` works without a manual ["targetId"] dance.
+    target_id = target.get("targetId") if isinstance(target, dict) else target
+    # Unmark old tab
+    try: cdp("Runtime.evaluate", expression="if(document.title.startsWith('\U0001F7E2 '))document.title=document.title.slice(2)")
+    except Exception: pass
+    cdp("Target.activateTarget", targetId=target_id)
+    sid = cdp("Target.attachToTarget", targetId=target_id, flatten=True)["sessionId"]
+    _send({"meta": "set_session", "session_id": sid, "target_id": target_id})
+    _mark_tab()
+    return sid
+
+def new_tab(url="about:blank"):
+    # Always create blank, then goto: passing url to createTarget races with
+    # attach, so the brief about:blank is "complete" by the time the caller
+    # polls and wait_for_load() returns before navigation actually starts.
+    tid = cdp("Target.createTarget", url="about:blank")["targetId"]
+    switch_tab(tid)
+    if url != "about:blank":
+        goto_url(url)
+    return tid
+
+def ensure_real_tab():
+    """Switch to a real user tab if current is chrome:// / internal / stale."""
+    tabs = list_tabs(include_chrome=False)
+    if not tabs:
+        return None
+    try:
+        cur = current_tab()
+        if cur["url"] and not cur["url"].startswith(INTERNAL):
+            return cur
+    except Exception:
+        pass
+    switch_tab(tabs[0]["targetId"])
+    return tabs[0]
+
+def iframe_target(url_substr):
+    """First iframe target whose URL contains `url_substr`. Use with js(..., target_id=...)."""
+    for t in cdp("Target.getTargets")["targetInfos"]:
+        if t["type"] == "iframe" and url_substr in t.get("url", ""):
+            return t["targetId"]
+    return None
+
+
+# --- utility ---
+def wait(seconds=1.0):
+    time.sleep(seconds)
+
+def wait_for_load(timeout=15.0):
+    """Poll document.readyState == 'complete' or timeout."""
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        if js("document.readyState") == "complete": return True
+        time.sleep(0.3)
+    return False
+
+def js(expression, target_id=None):
+    """Run JS in the attached tab (default) or inside an iframe target (via iframe_target()).
+
+    Expressions with top-level `return` are automatically wrapped in an IIFE, so both
+    `document.title` and `const x = 1; return x` are valid inputs.
+    """
+    sid = cdp("Target.attachToTarget", targetId=target_id, flatten=True)["sessionId"] if target_id else None
+    if _has_return_statement(expression) and not expression.strip().startswith("("):
+        expression = f"(function(){{{expression}}})()"
+    return _runtime_evaluate(expression, session_id=sid, await_promise=True)
+
+
+_KC = {"Enter": 13, "Tab": 9, "Escape": 27, "Backspace": 8, " ": 32, "ArrowLeft": 37, "ArrowUp": 38, "ArrowRight": 39, "ArrowDown": 40}
+
+
+def dispatch_key(selector, key="Enter", event="keypress"):
+    """Dispatch a DOM KeyboardEvent on the matched element.
+
+    Use this when a site reacts to synthetic DOM key events on an element more reliably
+    than to raw CDP input events.
+    """
+    kc = _KC.get(key, ord(key) if len(key) == 1 else 0)
+    js(
+        f"(()=>{{const e=document.querySelector({json.dumps(selector)});if(e){{e.focus();e.dispatchEvent(new KeyboardEvent({json.dumps(event)},{{key:{json.dumps(key)},code:{json.dumps(key)},keyCode:{kc},which:{kc},bubbles:true}}));}}}})()"
+    )
+
+def upload_file(selector, path):
+    """Set files on a file input via CDP DOM.setFileInputFiles. `path` is an absolute filepath (use tempfile.mkstemp if needed)."""
+    doc = cdp("DOM.getDocument", depth=-1)
+    nid = cdp("DOM.querySelector", nodeId=doc["root"]["nodeId"], selector=selector)["nodeId"]
+    if not nid: raise RuntimeError(f"no element for {selector}")
+    cdp("DOM.setFileInputFiles", files=[path] if isinstance(path, str) else list(path), nodeId=nid)
+
+def http_get(url, headers=None, timeout=20.0):
+    """Pure HTTP — no browser. Use for static pages / APIs. Wrap in ThreadPoolExecutor for bulk.
+
+    When BROWSER_USE_API_KEY is set, routes through the fetch-use proxy (handles bot
+    detection, residential proxies, retries). Falls back to local urllib otherwise."""
+    if os.environ.get("BROWSER_USE_API_KEY"):
+        try:
+            from fetch_use import fetch_sync
+            return fetch_sync(url, headers=headers, timeout_ms=int(timeout * 1000)).text
+        except ImportError:
+            pass
+    import gzip
+    h = {"User-Agent": "Mozilla/5.0", "Accept-Encoding": "gzip"}
+    if headers: h.update(headers)
+    with urllib.request.urlopen(urllib.request.Request(url, headers=h), timeout=timeout) as r:
+        data = r.read()
+        if r.headers.get("Content-Encoding") == "gzip": data = gzip.decompress(data)
+        return data.decode()
+
+
+def _load_agent_helpers():
+    p = AGENT_WORKSPACE / "agent_helpers.py"
+    if not p.exists():
+        return
+    spec = importlib.util.spec_from_file_location("browser_harness_agent_helpers", p)
+    if not spec or not spec.loader:
+        return
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    for name, value in vars(module).items():
+        if name.startswith("_"):
+            continue
+        globals()[name] = value
+
+
+_load_agent_helpers()

package/dist/extensions/builtin/browser/src/browser_harness/run.py

@@ -0,0 +1,103 @@
+"""Browser Harness CLI-compatible runner used by Catui subprocess tools.
+
+[WHO]: Provides main() command dispatch, daemon auto-start, setup/doctor/update/reload flags, and snippet execution
+[FROM]: Depends on browser_harness.admin, browser_harness.helpers, urllib, os, and sys
+[TO]: Consumed by Catui browser/browser_admin tools via python -m browser_harness.run
+[HERE]: extensions/builtin/browser/src/browser_harness/run.py within vendored Browser Harness package
+"""
+
+import os, sys, urllib.request
+
+# Windows default stdout encoding is cp1252, which can't encode the 🟢 marker
+# helpers prepend to tab titles (or anything else outside Latin-1). Force UTF-8
+# so `print(page_info())` doesn't UnicodeEncodeError on Windows. Issue #124(4).
+if hasattr(sys.stdout, "reconfigure"):
+    try: sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    except Exception: pass
+
+from .admin import (
+    _version,
+    NAME,
+    daemon_alive,
+    ensure_daemon,
+    list_cloud_profiles,
+    list_local_profiles,
+    print_update_banner,
+    restart_daemon,
+    run_doctor,
+    run_setup,
+    run_update,
+    start_remote_daemon,
+    stop_remote_daemon,
+    sync_local_profile,
+)
+from .helpers import *
+
+HELP = """Browser Harness
+
+Read SKILL.md for the default workflow and examples.
+
+Typical usage:
+  browser-harness -c '
+  ensure_real_tab()
+  print(page_info())
+  '
+
+Helpers are pre-imported. The daemon auto-starts and connects to the running browser.
+
+Commands:
+  browser-harness --version        print the installed version
+  browser-harness --doctor         diagnose install, daemon, and browser state
+  browser-harness --setup          interactively attach to your running browser
+  browser-harness --update [-y]    pull the latest version (agents: pass -y)
+  browser-harness --reload         stop the daemon so next call picks up code changes
+"""
+
+
+# Probe /json/version (not a bare TCP connect) so a non-Chrome process bound to
+# 9222/9223 doesn't masquerade as Chrome and skip the cloud bootstrap. Mirrors
+# daemon.py's fallback probe.
+def _local_chrome_listening():
+    for port in (9222, 9223):
+        try:
+            urllib.request.urlopen(f"http://127.0.0.1:{port}/json/version", timeout=0.3).close()
+            return True
+        except OSError: pass
+    return False
+
+
+def main():
+    args = sys.argv[1:]
+    if args and args[0] in {"-h", "--help"}:
+        print(HELP)
+        return
+    if args and args[0] == "--version":
+        print(_version() or "unknown")
+        return
+    if args and args[0] == "--doctor":
+        sys.exit(run_doctor())
+    if args and args[0] == "--setup":
+        sys.exit(run_setup())
+    if args and args[0] == "--update":
+        yes = any(a in {"-y", "--yes"} for a in args[1:])
+        sys.exit(run_update(yes=yes))
+    if args and args[0] == "--reload":
+        restart_daemon()
+        print("daemon stopped — will restart fresh on next call")
+        return
+    if args and args[0] == "--debug-clicks":
+        os.environ["BH_DEBUG_CLICKS"] = "1"
+        args = args[1:]
+    if not args or args[0] != "-c":
+        sys.exit("Usage: browser-harness -c \"print(page_info())\"")
+    if len(args) < 2:
+        sys.exit("Usage: browser-harness -c \"print(page_info())\"")
+    print_update_banner()
+    if not daemon_alive() and not _local_chrome_listening() and os.environ.get("BROWSER_USE_API_KEY"):
+        start_remote_daemon(NAME)
+    ensure_daemon()
+    exec(args[1], globals())
+
+
+if __name__ == "__main__":
+    main()

package/dist/extensions/builtin/btw/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * [WHO]: btwExtension - registers /btw command and BTW message renderer
+ * [FROM]: Depends on core/extensions-host/types
+ * [TO]: Auto-loaded by builtin-extensions.ts as a default extension
+ * [HERE]: extensions/builtin/btw/index.ts - quick side question without interrupting main task
+ */
+import type { ExtensionAPI } from "../../../core/extensions-host/types.js";
+export default function btwExtension(api: ExtensionAPI): Promise<void>;

package/dist/extensions/builtin/btw/index.js

@@ -0,0 +1,15 @@
+var d=Object.defineProperty;var a=(t,e)=>d(t,"name",{value:e,configurable:!0});import{Box as m,Container as g,Spacer as y,Text as p}from"@catui/tui";const l="btw",w=3e4,T=`You are answering a quick "by the way" question inline during an active coding session.
+
+Rules:
+- Answer directly and concisely - the user is waiting
+- Do NOT use any tools
+- Do NOT say "I cannot" or explain limitations
+- If you don't know, say so briefly
+- Keep responses short (1-3 sentences unless detail is critical).`,x=500;function f(t){return typeof t=="string"?t:t.filter(e=>e.type==="text").map(e=>e.text).join(`
+`)}a(f,"extractText");function h(t){const e=[];for(const i of t){const s=i;if(s.type==="message"){if(s.message.role==="user"){const o=f(s.message.content);o.trim()&&e.push(`User: ${o}`)}else if(s.message.role==="assistant"){const o=f(s.message.content);o.trim()&&e.push(`Assistant: ${o.slice(0,x)}`)}}}return e.slice(-20).join(`
+
+`)}a(h,"buildBtwContext");async function M(t,e,c){const i=t.trim();if(!i){e.ui.notify("Usage: /btw <question>","warning");return}const s=h(e.sessionManager.getEntries()),o=s?`Previous conversation:
+${s}
+
+User's question: ${i}`:`User's question: ${i}`;let r;try{const n=await Promise.race([e.completeSimple(T,o),new Promise(u=>{r=setTimeout(()=>u(void 0),w)})]);n?c.sendMessage({customType:l,content:n,display:!0}):e.ui.notify("BTW: No response from model (check API key)","warning")}catch(n){const u=n instanceof Error?n.message:String(n);e.ui.notify(`BTW error: ${u}`,"error")}finally{r&&clearTimeout(r)}}a(M,"handleBtwCommand");async function _(t){t.registerMessageRenderer(l,(e,c,i)=>{const s=typeof e.content=="string"?e.content:e.content.filter(n=>n.type==="text").map(n=>n.text).join(`
+`),o=new m(1,1,n=>i.bg("customMessageBg",n));o.addChild(new p(i.fg("dim",s),0,0));const r=new g;return r.addChild(new y(1)),r.addChild(o),r}),t.registerCommand("btw",{description:"Ask a quick side question while the main task keeps its place",handler:a((e,c)=>M(e,c,t),"handler")})}a(_,"btwExtension");export{_ as default};

package/dist/extensions/builtin/debug/collectors.d.ts

@@ -0,0 +1,96 @@
+/**
+ * [WHO]: Diagnostic data collectors for /debug command
+ * [FROM]: Depends on core/extensions-host/types, node:os, node:child_process
+ * [TO]: Consumed by extensions/builtin/debug/index.ts
+ * [HERE]: extensions/builtin/debug/collectors.ts - structured system state snapshots
+ */
+import type { ExtensionContext } from "../../../core/extensions-host/types.js";
+interface CollectorResult<T> {
+    data: T | null;
+    error: string | null;
+}
+export interface SystemInfo {
+    platform: string;
+    arch: string;
+    release: string;
+    nodeVersion: string;
+    hostname: string;
+    cpuCount: number;
+    cpuModel: string;
+    totalMemoryGB: number;
+    freeMemoryGB: number;
+    uptimeHours: number;
+    shell: string;
+    term: string;
+}
+export interface ModelInfo {
+    modelId: string;
+    modelName: string;
+    provider: string;
+    baseUrl: string;
+    reasoning: boolean;
+    contextWindow: number;
+    maxTokens: number;
+    contextUsagePercent: number | null;
+    contextTokens: number | null;
+}
+export interface SessionInfo {
+    sessionId: string;
+    sessionFile: string;
+    cwd: string;
+    sessionName: string | undefined;
+    entryCount: number;
+    leafId: string | null;
+}
+export interface ConfigInfo {
+    defaultProvider: string | undefined;
+    defaultModel: string | undefined;
+    thinkingLevel: string | undefined;
+    theme: string | undefined;
+    locale: string | undefined;
+    transport: string | undefined;
+    steeringMode: string | undefined;
+    extensionCount: number;
+    packageCount: number;
+}
+export interface GitInfo {
+    isRepo: boolean;
+    branch: string;
+    lastCommit: string;
+    statusSummary: string;
+    remoteUrl: string;
+}
+export interface AgentState {
+    isIdle: boolean;
+    hasPendingMessages: boolean;
+    systemPromptLength: number;
+    soulEnabled: boolean;
+}
+export interface DiagnosticData {
+    system: CollectorResult<SystemInfo>;
+    model: CollectorResult<ModelInfo>;
+    session: CollectorResult<SessionInfo>;
+    config: CollectorResult<ConfigInfo>;
+    git: CollectorResult<GitInfo>;
+    agent: CollectorResult<AgentState>;
+}
+export declare function collectSystemInfo(): Promise<CollectorResult<SystemInfo>>;
+export declare function collectModelInfo(ctx: ExtensionContext): Promise<CollectorResult<ModelInfo>>;
+export declare function collectSessionInfo(ctx: ExtensionContext): Promise<CollectorResult<SessionInfo>>;
+export declare function collectConfigInfo(ctx: ExtensionContext): Promise<CollectorResult<ConfigInfo>>;
+export declare function collectGitInfo(cwd: string): Promise<CollectorResult<GitInfo>>;
+export declare function collectAgentState(ctx: ExtensionContext): Promise<CollectorResult<AgentState>>;
+export declare function sanitizeForLLM(data: DiagnosticData): DiagnosticData;
+export declare function formatDiagnosticData(data: DiagnosticData): string;
+export interface PreferencesInfo {
+    locale: string;
+    localeSource: "memory" | "settings" | "system";
+    memoryDir: string;
+    languagePreference: {
+        found: boolean;
+        name?: string;
+        summary?: string;
+    }[];
+}
+export declare function collectPreferencesInfo(ctx: ExtensionContext): Promise<CollectorResult<PreferencesInfo>>;
+export {};

package/dist/extensions/builtin/debug/collectors.js

@@ -0,0 +1,7 @@
+var x=Object.defineProperty;var n=(t,e)=>x(t,"name",{value:e,configurable:!0});import{execFile as E}from"node:child_process";import*as l from"node:os";import{promisify as I}from"node:util";const h=I(E),v=3e3,S=50;async function C(){try{const t=l.cpus();return{data:{platform:l.platform(),arch:l.arch(),release:l.release(),nodeVersion:process.version,hostname:l.hostname(),cpuCount:t.length,cpuModel:t[0]?.model??"unknown",totalMemoryGB:Number((l.totalmem()/1073741824).toFixed(1)),freeMemoryGB:Number((l.freemem()/1073741824).toFixed(1)),uptimeHours:Number((l.uptime()/3600).toFixed(1)),shell:process.env.SHELL??"unknown",term:process.env.TERM??"unknown"},error:null}}catch(t){return{data:null,error:`System info collection failed: ${t instanceof Error?t.message:String(t)}`}}}n(C,"collectSystemInfo");async function P(t){try{const e=t.model;if(!e)return{data:null,error:"No model configured"};const r=t.getContextUsage();return{data:{modelId:e.id,modelName:e.name,provider:e.provider,baseUrl:e.baseUrl,reasoning:e.reasoning,contextWindow:e.contextWindow,maxTokens:e.maxTokens,contextUsagePercent:r?.percent??null,contextTokens:r?.tokens??null},error:null}}catch(e){return{data:null,error:`Model info collection failed: ${e instanceof Error?e.message:String(e)}`}}}n(P,"collectModelInfo");async function R(t){try{const e=t.sessionManager;return{data:{sessionId:e.getSessionId(),sessionFile:e.getSessionFile()??"(none)",cwd:e.getCwd(),sessionName:e.getSessionName(),entryCount:e.getEntries().length,leafId:e.getLeafId()},error:null}}catch(e){return{data:null,error:`Session info collection failed: ${e instanceof Error?e.message:String(e)}`}}}n(R,"collectSessionInfo");async function $(t){try{const e=t.getSettings();return{data:{defaultProvider:e.defaultProvider,defaultModel:e.defaultModel,thinkingLevel:e.defaultThinkingLevel,theme:e.theme,locale:e.locale,transport:e.transport,steeringMode:e.steeringMode,extensionCount:e.extensions?.length??0,packageCount:e.packages?.length??0},error:null}}catch(e){return{data:null,error:`Config info collection failed: ${e instanceof Error?e.message:String(e)}`}}}n($,"collectConfigInfo");async function _(t){try{const e={cwd:t,timeout:v},[r,s,o,i]=await Promise.allSettled([h("git",["rev-parse","--abbrev-ref","HEAD"],e),h("git",["log","-1","--oneline"],e),h("git",["status","--short"],e),h("git",["remote","get-url","origin"],e)]),a=r.status==="fulfilled"?r.value.stdout.trim():"(unknown)",p=s.status==="fulfilled"?s.value.stdout.trim():"(none)",c=o.status==="fulfilled"?o.value.stdout.trim():"",u=c?c.split(`
+`):[],d=u.length>S?`${u.slice(0,S).join(`
+`)}
+... (${u.length-S} more files)`:c||"(clean)",y=i.status==="fulfilled"?i.value.stdout.trim():"(no remote)";return{data:{isRepo:!0,branch:a,lastCommit:p,statusSummary:d,remoteUrl:T(y)},error:null}}catch{return{data:{isRepo:!1,branch:"-",lastCommit:"-",statusSummary:"-",remoteUrl:"-"},error:"Not a git repository or git not available"}}}n(_,"collectGitInfo");async function F(t){try{return{data:{isIdle:t.isIdle(),hasPendingMessages:t.hasPendingMessages(),systemPromptLength:t.getSystemPrompt().length,soulEnabled:t.getSoulManager()!==void 0},error:null}}catch(e){return{data:null,error:`Agent state collection failed: ${e instanceof Error?e.message:String(e)}`}}}n(F,"collectAgentState");const k=/(?:api[_-]?key|token|secret|password|credential|auth)/i;function T(t){return t.replace(/:\/\/[^@]+@/,"://***@")}n(T,"sanitizeRemoteUrl");function L(t){const e=n(r=>{if(r==null||typeof r=="string")return r;if(Array.isArray(r))return r.map(e);if(typeof r=="object"){const s={};for(const[o,i]of Object.entries(r))k.test(o)&&typeof i=="string"?s[o]="***REDACTED***":s[o]=e(i);return s}return r},"sanitize");return{system:t.system.error?t.system:{data:e(t.system.data),error:null},model:t.model.error?t.model:{data:e(t.model.data),error:null},session:t.session.error?t.session:{data:e(t.session.data),error:null},config:t.config.error?t.config:{data:e(t.config.data),error:null},git:t.git.error?t.git:{data:e(t.git.data),error:null},agent:t.agent.error?t.agent:{data:e(t.agent.data),error:null}}}n(L,"sanitizeForLLM");function m(t,e){const r=[`| ${t} | |`,"|---|---|"];for(const[s,o]of Object.entries(e)){const i=o===void 0?"(default)":o===null?"(null)":String(o);r.push(`| ${s} | ${i} |`)}return r.join(`
+`)}n(m,"formatAsTable");function g(t,e){return`> **${t}**: Collection failed: ${e}`}n(g,"formatError");function U(t){const e=[];return t.system.data?e.push(m("System",t.system.data)):t.system.error&&e.push(g("System",t.system.error)),t.model.data?e.push(m("Model",t.model.data)):t.model.error&&e.push(g("Model",t.model.error)),t.session.data?e.push(m("Session",t.session.data)):t.session.error&&e.push(g("Session",t.session.error)),t.config.data?e.push(m("Config",t.config.data)):t.config.error&&e.push(g("Config",t.config.error)),t.git.data?e.push(m("Git",t.git.data)):t.git.error&&e.push(g("Git",t.git.error)),t.agent.data?e.push(m("Agent",t.agent.data)):t.agent.error&&e.push(g("Agent",t.agent.error)),e.join(`
+
+`)}n(U,"formatDiagnosticData");async function O(t){try{const e=await import("node:os"),r=await import("node:fs"),s=await import("node:path"),o=process.env.NANOMEM_MEMORY_DIR||s.join(e.homedir(),".catui","agent","memory");let i="en",a="system";const p=[],c=s.join(o,"preferences.json");if(r.existsSync(c))try{const y=JSON.parse(r.readFileSync(c,"utf-8")).filter(f=>{const M=(f.name||"")+(f.summary||"")+(f.detail||"");return/中文|chinese|语言|locale|zh/i.test(M)});if(y.length>0){i="zh",a="memory";for(const f of y.slice(0,3))p.push({found:!0,name:f.name,summary:(f.summary||"").slice(0,80)})}}catch{}const u=s.join(e.homedir(),".catui","agent","settings.json");if(a==="system"&&r.existsSync(u))try{const d=JSON.parse(r.readFileSync(u,"utf-8"));d.locale&&(i=d.locale,a="settings")}catch{}return{data:{locale:i,localeSource:a,memoryDir:o,languagePreference:p},error:null}}catch(e){return{data:null,error:String(e)}}}n(O,"collectPreferencesInfo");export{F as collectAgentState,$ as collectConfigInfo,_ as collectGitInfo,P as collectModelInfo,O as collectPreferencesInfo,R as collectSessionInfo,C as collectSystemInfo,U as formatDiagnosticData,L as sanitizeForLLM};

package/dist/extensions/builtin/debug/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * [WHO]: debugExtension - /debug command, before_agent_start hook injects diagnostic system prompt, agent_end cleanup, dispatched via sendUserMessage for streaming UX
+ * [FROM]: Depends on core/extensions-host/types, @catui/tui, ./collectors
+ * [TO]: Auto-loaded by builtin-extensions.ts as a default extension
+ * [HERE]: extensions/builtin/debug/index.ts - system diagnostics with three-layer analysis through full agent loop
+ */
+import type { ExtensionAPI } from "../../../core/extensions-host/types.js";
+export default function debugExtension(api: ExtensionAPI): Promise<void>;