subcortex 0.3.0__py3-none-any.whl

subcortex/installers/openhands.py

@@ -0,0 +1,84 @@
+"""OpenHands CLI: ``~/.openhands/hooks.json`` (+ optional ``mcp.json``).
+
+OpenHands loads exactly one hooks file — a project ``.openhands/hooks.json``
+replaces the user one entirely — and a file with an unknown event key or both
+key styles (``user_prompt_submit`` and ``UserPromptSubmit``) breaks conversation
+setup. So we reuse whatever style the file already has and add nothing else.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, Dict, List
+
+from .base import Installer, Target, add_grouped, json_target, mcp_json_target, remove_grouped
+
+SNAKE, PASCAL = "user_prompt_submit", "UserPromptSubmit"
+_PASCAL_KEYS = {"PreToolUse", "PostToolUse", "UserPromptSubmit", "Stop", "SessionStart", "SessionEnd"}
+
+
+def _table(data: Dict[str, Any]) -> Dict[str, Any]:
+    wrapper = data.get("hooks")
+    return wrapper if isinstance(wrapper, dict) else data
+
+
+def persistence_dir() -> Path:
+    override = os.environ.get("OPENHANDS_PERSISTENCE_DIR", "").strip()
+    return Path(override) if override else Path.home() / ".openhands"
+
+
+class OpenHandsInstaller(Installer):
+    name = "openhands"
+    display_name = "OpenHands CLI"
+    seam = "hooks"
+    binaries = ("openhands",)
+    docs = "https://docs.openhands.dev/openhands/usage/customization/hooks"
+    min_version = "1.12.0"
+    supports_mcp = True
+    post_install = "applies to new OpenHands conversations"
+
+    def _entry(self) -> Dict[str, Any]:
+        return {"type": "command", "command": self.command("UserPromptSubmit"), "timeout": 10}
+
+    def targets(self) -> List[Target]:
+        def add(data: Dict[str, Any]) -> None:
+            table = _table(data)
+            key = PASCAL if any(k in _PASCAL_KEYS for k in table) else SNAKE
+            add_grouped(table, key, "*", self._entry())
+
+        def remove(data: Dict[str, Any]) -> None:
+            remove_grouped(_table(data))
+
+        def installed(data: Dict[str, Any]) -> bool:
+            probe = {k: v for k, v in _table(data).items() if isinstance(v, list)}
+            return bool(remove_grouped(probe))
+
+        targets = [json_target(Path.home() / ".openhands" / "hooks.json", add, remove, installed)]
+        if self.mcp:
+            targets.append(mcp_json_target(
+                persistence_dir() / "mcp.json", self.mcp_command(),
+                extra={"transport": "stdio", "enabled": True}))
+        return targets
+
+    def warnings(self) -> List[str]:
+        try:
+            project = Path.cwd() / ".openhands" / "hooks.json"
+        except OSError:  # cwd was deleted
+            return []
+        if project.is_file():
+            return [f"{project} exists and replaces the user-level hooks file inside this "
+                    "project; subcortex will not run here unless you add it there too"]
+        return []
+
+    def hook_events(self) -> List[str]:
+        return ["UserPromptSubmit"]
+
+    def sample_payload(self, event: str) -> Dict[str, Any]:
+        return {"event_type": "UserPromptSubmit", "tool_name": None, "tool_input": None,
+                "tool_response": None, "message": "what does ls -la do?",
+                "session_id": "4f1c2a9e-8b7d-4e21-9c3a-0d5e6f7a8b9c",
+                "working_dir": "/tmp", "metadata": {}}
+
+    def expects_output(self, event: str) -> bool:
+        return True

subcortex/installers/pi_cline.py

@@ -0,0 +1,53 @@
+"""Pi and Cline CLI: one TypeScript plugin file each (+ optional MCP for Cline).
+
+Both load every file in their plugin directory, so the plugin is a single
+self-contained file with type-only imports. Pi exits on a plugin load error
+and Cline fails the run on a hook error or a hook slower than 3 s — the
+plugins catch everything and race every hook against a deadline, and
+tests/test_plugins.py runs them under Bun against a live daemon.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import List
+
+from .base import Installer, Target, rendered_plugin, mcp_json_target, plugin_file_target
+from .mcp_only import cline_dir, cline_mcp_path
+
+
+class PiInstaller(Installer):
+    name = "pi"
+    display_name = "Pi"
+    seam = "plugin"
+    binaries = ("pi",)
+    docs = "https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/extensions.md"
+    min_version = "0.87.0"
+    post_install = "new pi sessions load the extension"
+
+    def extensions_dir(self) -> Path:
+        override = os.environ.get("PI_CODING_AGENT_DIR", "").strip()
+        return (Path(override) if override else Path.home() / ".pi" / "agent") / "extensions"
+
+    def targets(self) -> List[Target]:
+        content = rendered_plugin("pi")
+        return [plugin_file_target(self.extensions_dir() / "subcortex.ts", content)]
+
+
+class ClineInstaller(Installer):
+    name = "cline"
+    display_name = "Cline CLI"
+    seam = "plugin"
+    binaries = ("cline",)
+    docs = "https://docs.cline.bot/sdk/plugins"
+    min_version = "3.0.62"
+    supports_mcp = True
+    post_install = "new cline runs load the plugin"
+
+    def targets(self) -> List[Target]:
+        content = rendered_plugin("cline")
+        targets = [plugin_file_target(cline_dir() / "plugins" / "subcortex.ts", content)]
+        if self.mcp:
+            targets.append(mcp_json_target(cline_mcp_path(), self.mcp_command(), extra={"type": "stdio"}))
+        return targets

subcortex/ledger.py

@@ -0,0 +1,92 @@
+"""What subcortex did, for ``subcortex stats``: one JSON line per event.
+
+Hooks and the daemon append counts only — never prompts or output — to a
+private (0600) file in the data dir. Appends of one short line are atomic, so
+concurrent hook processes need no lock. The file rotates at ``MAX_BYTES``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from typing import Any, Dict, Iterator, Optional
+
+from .config import data_dir
+
+MAX_BYTES = 5_000_000
+
+
+def _path():
+    return data_dir() / "ledger.jsonl"
+
+
+def record(kind: str, tui: str = "", **fields: Any) -> None:
+    """Append one event (``hint``, ``trim``, ``restore``, ``jev``). Never raises."""
+    try:
+        path = _path()
+        path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+        try:
+            if path.stat().st_size > MAX_BYTES:
+                os.replace(path, path.with_name("ledger.1.jsonl"))
+        except FileNotFoundError:
+            pass
+        line = json.dumps({"t": int(time.time()), "k": kind, "tui": tui, **fields},
+                          separators=(",", ":")) + "\n"
+        fd = os.open(path, os.O_WRONLY | os.O_APPEND | os.O_CREAT, 0o600)
+        try:
+            os.write(fd, line.encode("utf-8"))
+        finally:
+            os.close(fd)
+    except Exception:
+        pass
+
+
+def _events() -> Iterator[Dict[str, Any]]:
+    for name in ("ledger.1.jsonl", "ledger.jsonl"):
+        try:
+            with open(data_dir() / name, encoding="utf-8") as fh:
+                for line in fh:
+                    try:
+                        event = json.loads(line)
+                    except ValueError:
+                        continue
+                    if isinstance(event, dict):
+                        yield event
+        except OSError:
+            continue
+
+
+def summary(since: Optional[float] = None) -> Dict[str, Any]:
+    """Totals overall and per TUI, optionally only for events after ``since``."""
+    total: Dict[str, Any] = {"hints": 0, "trims": 0, "chars_removed": 0, "restores": 0,
+                             "jev_calls": 0, "jev_input_tokens": 0, "jev_cost_usd": 0.0}
+    per_tui: Dict[str, Dict[str, int]] = {}
+    first = None
+    for event in _events():
+        t = event.get("t") or 0
+        if since is not None and t < since:
+            continue
+        first = t if first is None else min(first, t)
+        kind, tui = event.get("k"), str(event.get("tui") or "?")
+        row = per_tui.setdefault(tui, {"hints": 0, "trims": 0, "chars_removed": 0, "restores": 0})
+        if kind == "hint":
+            total["hints"] += 1
+            row["hints"] += 1
+        elif kind == "trim":
+            removed = max(0, int(event.get("before", 0)) - int(event.get("after", 0)))
+            total["trims"] += 1
+            total["chars_removed"] += removed
+            row["trims"] += 1
+            row["chars_removed"] += removed
+        elif kind == "restore":
+            total["restores"] += 1
+            row["restores"] += 1
+        elif kind == "jev":
+            total["jev_calls"] += 1
+            total["jev_input_tokens"] += int(event.get("tokens", 0))
+            total["jev_cost_usd"] += float(event.get("usd", 0.0))
+    total["jev_cost_usd"] = round(total["jev_cost_usd"], 6)
+    per_tui = {k: v for k, v in per_tui.items() if k != "?" or any(v.values())}
+    return {"since": first, "total": total,
+            "per_tui": {k: v for k, v in per_tui.items() if any(v.values())}}

subcortex/localhttp.py

@@ -0,0 +1,59 @@
+"""HTTP to the local daemon over a direct socket to 127.0.0.1, and nothing else.
+
+Not urllib: urllib honors HTTP_PROXY and the system proxy settings, so on a
+machine with a proxy configured, requests for 127.0.0.1 (carrying prompts and
+tool output) went to the proxy, or failed. It is also the slowest import in a
+hook process (~15 ms). The daemon answers HTTP/1.0: one request per connection,
+closed after the reply, which is all this client needs to handle.
+"""
+
+from __future__ import annotations
+
+import json
+import socket
+import time
+from typing import Any, Dict, Optional, Tuple
+
+MAX_RESPONSE_BYTES = 8_000_000
+
+
+class LocalHTTPError(OSError):
+    """The daemon answered something that is not a well-formed HTTP reply."""
+
+
+def request(port: int, method: str, path: str, payload: Optional[Dict[str, Any]] = None,
+            timeout: float = 3.0) -> Tuple[int, Any]:
+    """``(status, parsed JSON body)``. Raises OSError (incl. ConnectionRefusedError,
+    TimeoutError) or ValueError; the whole exchange is bounded by ``timeout``."""
+    from .auth import HEADER, read_token
+
+    body = b"" if payload is None else json.dumps(payload).encode("utf-8")
+    head = (f"{method} {path} HTTP/1.0\r\nHost: 127.0.0.1:{int(port)}\r\n"
+            f"Content-Type: application/json\r\nContent-Length: {len(body)}\r\n"
+            f"{HEADER}: {read_token()}\r\nX-Subcortex-Timeout-Ms: {int(timeout * 1000)}\r\n\r\n")
+    deadline = time.monotonic() + timeout
+    chunks, size = [], 0
+    # One deadline for the whole exchange: connect, send and every read share it.
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+        sock.settimeout(timeout)
+        sock.connect(("127.0.0.1", int(port)))
+        sock.settimeout(max(0.01, deadline - time.monotonic()))
+        sock.sendall(head.encode("ascii") + body)
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise TimeoutError("daemon reply timed out")
+            sock.settimeout(remaining)
+            chunk = sock.recv(65536)
+            if not chunk:
+                break
+            size += len(chunk)
+            if size > MAX_RESPONSE_BYTES:
+                raise LocalHTTPError("daemon reply too large")
+            chunks.append(chunk)
+    raw = b"".join(chunks)
+    header, sep, rest = raw.partition(b"\r\n\r\n")
+    status_line = header.split(b"\r\n", 1)[0].split(b" ", 2)
+    if not sep or len(status_line) < 2 or not status_line[0].startswith(b"HTTP/"):
+        raise LocalHTTPError("malformed daemon reply")
+    return int(status_line[1]), (json.loads(rest) if rest.strip() else None)

subcortex/mcp_server.py

@@ -0,0 +1,187 @@
+"""Minimal stdio MCP server exposing subcortex decisions as tools.
+
+This is the generic seam for any MCP-capable TUI (Gemini CLI, Crush, Amp, Cursor…)
+where we don't ship a native hook adapter: the agent can call these tools on demand.
+Automatic interception (prompt classify, output filtering) lives in the hook
+adapters — MCP tools are model-invoked, so they serve on-demand decisions only.
+
+Zero dependencies. Transport per the MCP spec's stdio transport: one JSON-RPC
+message per line (UTF-8, newline-delimited, no embedded newlines) on
+stdin/stdout; nothing but protocol messages is ever written to stdout.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import sys
+from typing import Any, Dict, Optional
+
+from . import __version__
+
+logger = logging.getLogger(__name__)
+
+_PROTOCOL_VERSION = "2025-06-18"
+_SUPPORTED_VERSIONS = ("2025-06-18", "2025-03-26", "2024-11-05")
+_SERVER_INFO = {"name": "subcortex", "version": __version__}
+
+_TOOLS = [
+    {
+        "name": "subcortex_decide",
+        "description": (
+            "Fast typed decision (choice/score/boolean with calibrated probabilities) "
+            "from the local subcortex service — routing, triage, gating, moderation. "
+            "Milliseconds, no LLM tokens."
+        ),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "state": {"description": "The situation to judge (text or JSON)."},
+                "questions": {
+                    "type": "object",
+                    "description": "Map of name -> {type: choice|score|noul, instructions, criteria?}",
+                },
+            },
+            "required": ["state", "questions"],
+        },
+    },
+    {
+        "name": "subcortex_classify_prompt",
+        "description": "Classify a user prompt as simple or complex (with confidence).",
+        "inputSchema": {
+            "type": "object",
+            "properties": {"prompt": {"type": "string"}},
+            "required": ["prompt"],
+        },
+    },
+    {
+        "name": "subcortex_judge_output",
+        "description": ("Judge whether a tool/command output is still needed for a request, or "
+                        "disposable. Without the request the output is always kept."),
+        "inputSchema": {
+            "type": "object",
+            "properties": {
+                "output": {"type": "string"},
+                "context": {"type": "string", "description": "What produced the output."},
+                "task": {"type": "string", "description": "The user's request the output serves."},
+            },
+            "required": ["output", "task"],
+        },
+    },
+]
+
+
+def _ensure_daemon() -> None:
+    """Start the daemon on first use if it isn't running (best effort; honors
+    hooks.autostart_daemon, and waits less than MCP clients' ~10 s timeout)."""
+    from . import cli
+    from .config import load_config
+
+    cfg = load_config()
+    if not (cfg.get("hooks") or {}).get("autostart_daemon", True):
+        return
+    if cli._health(cfg) is None:
+        cli._spawn_daemon(cfg)
+        cli._wait_for_health(cfg, timeout_s=8.0)
+
+
+def _post(path: str, body: Dict[str, Any]) -> Dict[str, Any]:
+    from . import localhttp
+    from .config import load_config
+
+    port = int(load_config()["port"])
+    try:
+        _, reply = localhttp.request(port, "POST", path, body, timeout=30)
+    except ConnectionRefusedError:
+        _ensure_daemon()
+        _, reply = localhttp.request(port, "POST", path, body, timeout=30)
+    if not isinstance(reply, dict):
+        raise ValueError("daemon reply is not a JSON object")
+    return reply
+
+
+def _call_tool(name: str, arguments: Dict[str, Any]) -> Dict[str, Any]:
+    if name == "subcortex_decide":
+        return _post("/decide", {"state": arguments.get("state"),
+                                 "questions": arguments.get("questions") or {}})
+    if name == "subcortex_classify_prompt":
+        return _post("/verdict/prompt", {"prompt": arguments.get("prompt", "")})
+    if name == "subcortex_judge_output":
+        return _post("/verdict/output", {"output": arguments.get("output", ""),
+                                         "context": arguments.get("context", ""),
+                                         "task": arguments.get("task", "")})
+    raise ValueError(f"unknown tool {name!r}")
+
+
+def _handle(request: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    """One JSON-RPC request -> response (None for notifications)."""
+    method = request.get("method", "")
+    req_id = request.get("id")
+
+    def result(value: Any) -> Dict[str, Any]:
+        return {"jsonrpc": "2.0", "id": req_id, "result": value}
+
+    def error(code: int, message: str) -> Dict[str, Any]:
+        return {"jsonrpc": "2.0", "id": req_id, "error": {"code": code, "message": message}}
+
+    if method == "initialize":
+        requested = (request.get("params") or {}).get("protocolVersion")
+        return result({
+            "protocolVersion": requested if requested in _SUPPORTED_VERSIONS else _PROTOCOL_VERSION,
+            "capabilities": {"tools": {}},
+            "serverInfo": _SERVER_INFO,
+        })
+    if method in ("notifications/initialized", "notifications/cancelled"):
+        return None
+    if method == "ping":
+        return result({})
+    if method == "tools/list":
+        return result({"tools": _TOOLS})
+    if method == "tools/call":
+        params = request.get("params") or {}
+        try:
+            outcome = _call_tool(params.get("name", ""), params.get("arguments") or {})
+            return result({"content": [{"type": "text", "text": json.dumps(outcome)}]})
+        except Exception as exc:
+            return result({"content": [{"type": "text", "text": f"subcortex error: {exc}"}],
+                           "isError": True})
+    if req_id is None:
+        return None
+    return error(-32601, f"method not found: {method}")
+
+
+def _respond(message: Any) -> Optional[Any]:
+    """Response for one parsed message (a request object or a legacy batch)."""
+    if isinstance(message, list):
+        replies = [r for r in (_respond(m) for m in message) if r is not None]
+        return replies or None
+    if not isinstance(message, dict):
+        return {"jsonrpc": "2.0", "id": None, "error": {"code": -32600, "message": "invalid request"}}
+    try:
+        return _handle(message)
+    except Exception as exc:  # never die on one bad request
+        logger.debug("mcp: handler error: %s", exc)
+        if message.get("id") is None:
+            return None
+        return {"jsonrpc": "2.0", "id": message["id"],
+                "error": {"code": -32603, "message": str(exc)}}
+
+
+def serve(stdin=None, stdout=None) -> None:
+    """Run the stdio MCP server loop until EOF."""
+    stdin = stdin or sys.stdin
+    stdout = stdout or sys.stdout
+    for line in stdin:
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            message = json.loads(line)
+        except ValueError:
+            reply: Any = {"jsonrpc": "2.0", "id": None,
+                          "error": {"code": -32700, "message": "parse error"}}
+        else:
+            reply = _respond(message)
+        if reply is not None:
+            stdout.write(json.dumps(reply, ensure_ascii=False) + "\n")
+            stdout.flush()

subcortex/metrics.py

@@ -0,0 +1,56 @@
+"""Simple in-memory counters + uptime, exposed by /stats."""
+
+from __future__ import annotations
+
+import threading
+import time
+from typing import Any, Dict, Optional
+
+
+class Metrics:
+    def __init__(self) -> None:
+        self._lock = threading.Lock()
+        self._started = time.time()
+        self._counts: Dict[str, int] = {}
+        self._latency_totals: Dict[str, float] = {}
+        self._sums: Dict[str, float] = {}
+        self._notes: Dict[str, str] = {}
+
+    def record(self, name: str, latency_ms: Optional[float] = None) -> None:
+        with self._lock:
+            self._counts[name] = self._counts.get(name, 0) + 1
+            if latency_ms is not None:
+                self._latency_totals[name] = self._latency_totals.get(name, 0.0) + latency_ms
+
+    def add(self, name: str, amount: float) -> None:
+        """Accumulate a quantity (tokens, dollars, characters)."""
+        with self._lock:
+            self._sums[name] = self._sums.get(name, 0) + amount
+
+    def note(self, name: str, value: str) -> None:
+        """Remember the latest value of something (e.g. the model that answered)."""
+        with self._lock:
+            self._notes[name] = value
+
+    def snapshot(self) -> Dict[str, Any]:
+        with self._lock:
+            counts = dict(self._counts)
+            totals = dict(self._latency_totals)
+            sums = {k: round(v, 6) if isinstance(v, float) else v for k, v in self._sums.items()}
+            notes = dict(self._notes)
+            started = self._started
+        avg = {
+            name: round(totals[name] / counts[name], 2)
+            for name in totals
+            if counts.get(name)
+        }
+        return {
+            "uptime_s": round(time.time() - started, 1),
+            "counts": counts,
+            "avg_latency_ms": avg,
+            "totals": sums,
+            "latest": notes,
+        }
+
+
+METRICS = Metrics()