switchroom 0.12.27 → 0.12.28

package/vendor/hindsight-memory/scripts/lib/daemon.py

@@ -0,0 +1,334 @@
+"""Hindsight-embed daemon lifecycle management.
+
+Port of: HindsightServer in @vectorize-io/hindsight-all, adapted for Python
+subprocess calls from ephemeral hook processes.
+
+Manages three connection modes (same as Openclaw):
+  1. External API — user provides hindsightApiUrl (skip daemon entirely)
+  2. Existing local server — user already has hindsight running
+  3. Auto-managed daemon — plugin starts/stops hindsight-embed
+
+In Claude Code's ephemeral model, daemon state is tracked via files in
+$CLAUDE_PLUGIN_DATA/state/. The daemon itself is a background OS process
+managed by hindsight-embed's built-in daemon command.
+"""
+
+import os
+import platform
+import subprocess
+import time
+import urllib.error
+import urllib.request
+
+from .client import USER_AGENT
+from .llm import detect_llm_config, get_llm_env_vars
+from .state import read_state, write_state
+
+DAEMON_STATE_FILE = "daemon.json"
+PROFILE_NAME = "claude-code"
+
+
+def _get_embed_command(config: dict) -> list:
+    """Get the command to run hindsight-embed.
+
+    Port of: getEmbedCommand() in @vectorize-io/hindsight-all
+    """
+    embed_path = config.get("embedPackagePath")
+    if embed_path:
+        return ["uv", "run", "--directory", embed_path, "hindsight-embed"]
+
+    version = config.get("embedVersion", "latest")
+    package = f"hindsight-embed@{version}" if version else "hindsight-embed@latest"
+    return ["uvx", package]
+
+
+def _run_embed(config: dict, args: list, env: dict = None, timeout: int = 10) -> subprocess.CompletedProcess:
+    """Run a hindsight-embed command and return the result."""
+    cmd = _get_embed_command(config) + args
+    run_env = dict(os.environ)
+    if env:
+        run_env.update(env)
+    return subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+        env=run_env,
+    )
+
+
+def _is_embed_available(config: dict) -> bool:
+    """Quick check if hindsight-embed is available on PATH.
+
+    Avoids the slow uvx download path when the tool isn't installed.
+    """
+    import shutil
+
+    embed_path = config.get("embedPackagePath")
+    if embed_path:
+        return os.path.isdir(embed_path)
+    # Check for uvx or hindsight-embed on PATH
+    return shutil.which("uvx") is not None or shutil.which("hindsight-embed") is not None
+
+
+def _check_health(base_url: str, timeout: int = 2) -> bool:
+    """Quick health check against a Hindsight server."""
+    try:
+        url = f"{base_url.rstrip('/')}/health"
+        req = urllib.request.Request(url, method="GET", headers={"User-Agent": USER_AGENT})
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return resp.status == 200
+    except Exception:
+        return False
+
+
+def get_api_url(config: dict, debug_fn=None, allow_daemon_start: bool = False) -> str:
+    """Determine the API URL, optionally starting daemon if needed.
+
+    Returns the API URL to use for recall/retain, handling all three modes.
+
+    Connection mode priority:
+      1. External API (hindsightApiUrl configured)
+      2. Existing local server (check port health)
+      3. Auto-managed daemon (only if allow_daemon_start=True)
+
+    The allow_daemon_start flag prevents the recall hook (10s timeout) from
+    blocking on a 30s daemon startup. Only the retain hook (async, 15s) should
+    attempt daemon start.
+    """
+    # Mode 1: External API
+    external_url = config.get("hindsightApiUrl")
+    if external_url:
+        if debug_fn:
+            debug_fn(f"Using external API: {external_url}")
+        return external_url
+
+    # Mode 2 & 3: Local server
+    port = config.get("apiPort", 9077)
+    base_url = f"http://127.0.0.1:{port}"
+
+    # Check if something is already running on this port
+    if _check_health(base_url):
+        if debug_fn:
+            debug_fn(f"Existing server healthy on port {port}")
+        return base_url
+
+    # Mode 3: Auto-start daemon (only when allowed)
+    if not allow_daemon_start:
+        raise RuntimeError(
+            f"No Hindsight server on port {port}. Set hindsightApiUrl for external "
+            f"API, start hindsight-embed manually, or wait for the retain hook to "
+            f"auto-start the daemon."
+        )
+
+    if debug_fn:
+        debug_fn(f"No server on port {port}, attempting daemon start")
+
+    try:
+        _ensure_daemon_running(config, port, debug_fn)
+    except Exception as e:
+        if debug_fn:
+            debug_fn(f"Daemon start failed: {e}")
+        raise RuntimeError(
+            "No Hindsight server available. Set hindsightApiUrl for external API, "
+            "or ensure hindsight-embed is installed for local daemon mode."
+        ) from e
+
+    return base_url
+
+
+def _ensure_daemon_running(config: dict, port: int, debug_fn=None):
+    """Start the hindsight-embed daemon if not already running.
+
+    Port of: HindsightServer.start() in @vectorize-io/hindsight-all
+    """
+    # Fast-fail if hindsight-embed toolchain is not available
+    if not _is_embed_available(config):
+        raise RuntimeError(
+            "hindsight-embed not found (uvx not on PATH). "
+            "Install with: pip install hindsight-embed, or set hindsightApiUrl."
+        )
+
+    base_url = f"http://127.0.0.1:{port}"
+
+    # Detect LLM config (needed for daemon's fact extraction)
+    try:
+        llm_config = detect_llm_config(config)
+    except RuntimeError as e:
+        raise RuntimeError(f"Cannot start daemon: {e}") from e
+
+    llm_env = get_llm_env_vars(llm_config)
+
+    # Build daemon environment
+    daemon_env = dict(llm_env)
+    idle_timeout = config.get("daemonIdleTimeout", 300)
+    daemon_env["HINDSIGHT_EMBED_DAEMON_IDLE_TIMEOUT"] = str(idle_timeout)
+
+    # On macOS, force CPU for embeddings/reranker (mirrors Openclaw)
+    if platform.system() == "Darwin":
+        daemon_env["HINDSIGHT_API_EMBEDDINGS_LOCAL_FORCE_CPU"] = "1"
+        daemon_env["HINDSIGHT_API_RERANKER_LOCAL_FORCE_CPU"] = "1"
+
+    # Step 1: Configure profile
+    if debug_fn:
+        debug_fn(f'Configuring "{PROFILE_NAME}" profile...')
+
+    profile_args = [
+        "profile",
+        "create",
+        PROFILE_NAME,
+        "--merge",
+        "--port",
+        str(port),
+    ]
+    for env_name, env_val in daemon_env.items():
+        if env_val:
+            profile_args.extend(["--env", f"{env_name}={env_val}"])
+
+    try:
+        result = _run_embed(config, profile_args, daemon_env, timeout=10)
+        if result.returncode != 0:
+            if debug_fn:
+                debug_fn(f"Profile create stderr: {result.stderr.strip()}")
+            raise RuntimeError(f"Profile create failed (exit {result.returncode}): {result.stderr}")
+        if debug_fn:
+            debug_fn("Profile configured")
+    except subprocess.TimeoutExpired:
+        raise RuntimeError("Profile create timed out")
+    except FileNotFoundError:
+        raise RuntimeError(
+            "hindsight-embed not found. Install with: pip install hindsight-embed "
+            "or set hindsightApiUrl for external API mode."
+        )
+
+    # Step 2: Start daemon
+    if debug_fn:
+        debug_fn("Starting daemon...")
+
+    try:
+        result = _run_embed(
+            config,
+            ["daemon", "--profile", PROFILE_NAME, "start"],
+            daemon_env,
+            timeout=30,
+        )
+        if debug_fn:
+            debug_fn(f"Daemon start exit={result.returncode} stdout={result.stdout.strip()}")
+        if result.returncode != 0 and "already running" not in result.stderr.lower():
+            raise RuntimeError(f"Daemon start failed (exit {result.returncode}): {result.stderr}")
+    except subprocess.TimeoutExpired:
+        raise RuntimeError("Daemon start timed out")
+
+    # Step 3: Wait for ready (poll health endpoint)
+    if debug_fn:
+        debug_fn("Waiting for daemon to be ready...")
+
+    for attempt in range(30):
+        if _check_health(base_url):
+            if debug_fn:
+                debug_fn(f"Daemon ready after {attempt + 1} attempts")
+            # Track that we started this daemon
+            write_state(
+                DAEMON_STATE_FILE,
+                {
+                    "port": port,
+                    "started_by_plugin": True,
+                    "started_at": time.time(),
+                    "pid": os.getpid(),
+                },
+            )
+            return
+        time.sleep(1)
+
+    raise RuntimeError("Daemon failed to become ready within 30 seconds")
+
+
+def prestart_daemon_background(config: dict, debug_fn=None):
+    """Fire off daemon startup in the background — non-blocking.
+
+    Called from SessionStart hook to warm up the daemon before the first
+    recall or retain hook fires. Returns immediately; the daemon starts
+    asynchronously as a detached OS process.
+    """
+    if config.get("hindsightApiUrl"):
+        return  # External API mode — no local daemon needed
+
+    port = config.get("apiPort", 9077)
+    if _check_health(f"http://127.0.0.1:{port}"):
+        if debug_fn:
+            debug_fn(f"Daemon already running on port {port}, skipping pre-start")
+        return
+
+    if not _is_embed_available(config):
+        if debug_fn:
+            debug_fn("hindsight-embed not available, skipping pre-start")
+        return
+
+    try:
+        llm_config = detect_llm_config(config)
+    except RuntimeError as e:
+        if debug_fn:
+            debug_fn(f"No LLM configured, skipping daemon pre-start: {e}")
+        return
+
+    llm_env = get_llm_env_vars(llm_config)
+    daemon_env = dict(os.environ)
+    daemon_env.update(llm_env)
+    idle_timeout = config.get("daemonIdleTimeout", 300)
+    daemon_env["HINDSIGHT_EMBED_DAEMON_IDLE_TIMEOUT"] = str(idle_timeout)
+    if platform.system() == "Darwin":
+        daemon_env["HINDSIGHT_API_EMBEDDINGS_LOCAL_FORCE_CPU"] = "1"
+        daemon_env["HINDSIGHT_API_RERANKER_LOCAL_FORCE_CPU"] = "1"
+
+    embed_cmd = _get_embed_command(config)
+
+    profile_args = ["profile", "create", PROFILE_NAME, "--merge", "--port", str(port)]
+    for env_name, env_val in llm_env.items():
+        if env_val:
+            profile_args.extend(["--env", f"{env_name}={env_val}"])
+
+    import shlex
+    profile_str = shlex.join(embed_cmd + profile_args)
+    daemon_str = shlex.join(embed_cmd + ["daemon", "--profile", PROFILE_NAME, "start"])
+
+    import subprocess as _sp
+    _sp.Popen(
+        f"{profile_str} && {daemon_str}",
+        shell=True,
+        env=daemon_env,
+        stdout=_sp.DEVNULL,
+        stderr=_sp.DEVNULL,
+        start_new_session=True,
+    )
+    if debug_fn:
+        debug_fn(f"Daemon pre-start initiated in background (port {port})")
+
+
+def stop_daemon(config: dict, debug_fn=None):
+    """Stop the daemon if it was started by this plugin.
+
+    Called during cleanup. Only stops if we started it (tracked in state).
+    """
+    state = read_state(DAEMON_STATE_FILE)
+    if not state or not state.get("started_by_plugin"):
+        if debug_fn:
+            debug_fn("Daemon not started by plugin, skipping stop")
+        return
+
+    if debug_fn:
+        debug_fn("Stopping daemon...")
+
+    try:
+        result = _run_embed(
+            config,
+            ["daemon", "--profile", PROFILE_NAME, "stop"],
+            timeout=10,
+        )
+        if debug_fn:
+            debug_fn(f"Daemon stop: {result.stdout.strip()}")
+    except Exception as e:
+        if debug_fn:
+            debug_fn(f"Daemon stop error: {e}")
+
+    # Clear state
+    write_state(DAEMON_STATE_FILE, {})

package/vendor/hindsight-memory/scripts/lib/directives.py

@@ -0,0 +1,119 @@
+"""Active directives fetching and formatting for the recall hook.
+
+Why this lives separately from `content.py`:
+  Hindsight's `reflect` MCP tool has an upstream bug
+  (vectorize-io/hindsight#1269) where tagged directives are silently dropped
+  from synthesis. Until that ships, we surface directives client-side as a
+  structurally distinct top-of-prompt block so the agent reads them every
+  turn — independent of whatever `reflect` does with them.
+
+  `list_directives` itself works correctly upstream — only `reflect` is
+  broken — so this is a pure client-side win.
+
+Failure mode: any error fetching directives (HTTP error, malformed
+response, timeout) returns an empty list and logs a single warn line to
+stderr. We never raise to the caller — directives are nice-to-have on the
+recall path; a directive-fetch failure must not kill the recall block.
+"""
+
+import sys
+from typing import Optional
+
+# Sanity cap on how many directives we ever inject into the prompt. Banks
+# with more active directives than this are pathological; truncate with a
+# footer so the agent knows there are more.
+MAX_DIRECTIVES = 15
+
+# Hard timeout for the list_directives call. The recall hook is on the
+# UserPromptSubmit critical path — we cannot block it for long.
+DIRECTIVES_TIMEOUT_SECONDS = 2
+
+
+def fetch_active_directives(client, bank_id: str, timeout: int = DIRECTIVES_TIMEOUT_SECONDS) -> list:
+    """Fetch active directives for a bank, sorted by priority (highest first).
+
+    Args:
+        client: A HindsightClient instance with a list_directives method.
+        bank_id: The bank to fetch directives from.
+        timeout: HTTP timeout in seconds.
+
+    Returns:
+        A list of directive dicts (each with id, name, content, priority,
+        tags, ...), sorted by priority descending. On any failure returns
+        an empty list and logs a single warn line to stderr — never raises.
+    """
+    try:
+        response = client.list_directives(bank_id=bank_id, active_only=True, timeout=timeout)
+    except Exception as e:
+        print(f"[Hindsight] list_directives failed for bank '{bank_id}': {e}", file=sys.stderr)
+        return []
+
+    if not isinstance(response, dict):
+        print(
+            f"[Hindsight] list_directives returned non-dict for bank '{bank_id}': "
+            f"{type(response).__name__}",
+            file=sys.stderr,
+        )
+        return []
+
+    items = response.get("items")
+    if not isinstance(items, list):
+        # Empty / malformed response — quiet success, no warn (banks with
+        # no directives are normal).
+        return []
+
+    # Filter to dicts only, then sort by priority descending. Treat missing
+    # priority as 0 so malformed entries sink to the bottom rather than
+    # crashing.
+    valid = [d for d in items if isinstance(d, dict)]
+    valid.sort(key=lambda d: d.get("priority", 0), reverse=True)
+    return valid
+
+
+def format_active_directives_block(directives: list, max_directives: int = MAX_DIRECTIVES) -> Optional[str]:
+    """Format directives into the <active_directives> block string.
+
+    Returns None if the list is empty — callers should omit the block
+    entirely rather than emitting an empty wrapper.
+
+    Format:
+        <active_directives>
+        The following are HARD RULES the agent must follow on this turn. ...
+
+        1. [P10] <name>: <content>
+        2. [P9] <name>: <content>
+        ...
+        (+N more, omitted)
+        </active_directives>
+    """
+    if not directives:
+        return None
+
+    total = len(directives)
+    truncated = directives[:max_directives]
+    omitted = total - len(truncated)
+
+    lines = [
+        "<active_directives>",
+        (
+            "The following are HARD RULES the agent must follow on this turn. "
+            "They are the bank's currently active directives, ordered by priority. "
+            "Apply them when formulating your response."
+        ),
+        "",
+    ]
+
+    for i, d in enumerate(truncated, start=1):
+        priority = d.get("priority", 0)
+        name = (d.get("name") or "").strip() or "(unnamed)"
+        content = (d.get("content") or "").strip()
+        # Content verbatim — directives are deliberately authored. Do not
+        # reformat or truncate.
+        lines.append(f"{i}. [P{priority}] {name}: {content}")
+
+    if omitted > 0:
+        lines.append("")
+        lines.append(f"(+{omitted} more, omitted)")
+
+    lines.append("</active_directives>")
+    return "\n".join(lines)

package/vendor/hindsight-memory/scripts/lib/gateway_ipc.py

@@ -0,0 +1,126 @@
+"""Minimal client for the switchroom telegram gateway's unix-socket IPC.
+
+Used by the auto-recall hook to push status updates to the user's Telegram
+draft during the silent gap between inbound and the agent's first tool
+call. See `update_placeholder` in
+`telegram-plugin/gateway/ipc-protocol.ts` for the wire format.
+
+Why a separate, tiny client (instead of importing the existing bridge):
+the recall hook is an ephemeral python subprocess invoked by Claude Code
+on every UserPromptSubmit. The bridge (telegram-plugin/bridge/) is
+TypeScript and lives inside the long-running claude process. Hooks can't
+share the bridge connection. Each hook fire opens its own one-shot
+unix-socket connection, sends one JSON line, closes. ~5 ms total.
+
+Failure-tolerant by design: every error path returns silently. The
+recall hook MUST NOT block on a Telegram UX nice-to-have.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import socket
+from typing import Optional
+
+# Same regex `bin/auto-recall-hook.sh` (now removed) used; mirrors the
+# `<channel ...>` wrapper that telegram-plugin emits on inbound. Kept
+# permissive — attribute order varies, attributes can be quoted with " or
+# (rarely) ' depending on tooling.
+_CHANNEL_OPEN_RE = re.compile(
+    r"<channel\b[^>]*\bchat_id=[\"']([^\"']+)[\"'][^>]*>",
+    re.IGNORECASE,
+)
+
+
+def extract_chat_id_from_prompt(prompt: str) -> Optional[str]:
+    """Pull `chat_id` out of a `<channel ...>...</channel>` wrapper.
+
+    Returns None when the prompt isn't channel-wrapped (e.g. interactive
+    sessions, non-Telegram channels, or test fixtures). Caller should
+    silently skip the IPC update when None — there's no user-visible
+    draft to update.
+    """
+    if not prompt or not isinstance(prompt, str):
+        return None
+    # Inspect only the first 1 KB — the wrapper is always at the head;
+    # anchoring there caps the regex cost regardless of prompt size.
+    head = prompt[:1024]
+    match = _CHANNEL_OPEN_RE.search(head)
+    if not match:
+        return None
+    chat_id = match.group(1).strip()
+    return chat_id or None
+
+
+def gateway_socket_path() -> Optional[str]:
+    """Resolve the gateway socket path for the current agent.
+
+    Order of resolution:
+      1. SWITCHROOM_GATEWAY_SOCKET env var (explicit override).
+      2. <agent_dir>/telegram/gateway.sock — the conventional path
+         that gateway.ts uses by default.
+
+    Returns None when neither is available; callers no-op on None.
+    """
+    explicit = os.environ.get("SWITCHROOM_GATEWAY_SOCKET", "").strip()
+    if explicit:
+        return explicit
+    # CLAUDE_PLUGIN_DATA → <agent_dir>/.claude/plugins/data/<plugin>/.
+    # Step up four to land at <agent_dir>.
+    plugin_data = os.environ.get("CLAUDE_PLUGIN_DATA", "").strip()
+    if plugin_data:
+        agent_dir = os.path.normpath(os.path.join(plugin_data, "..", "..", "..", ".."))
+        candidate = os.path.join(agent_dir, "telegram", "gateway.sock")
+        if os.path.exists(candidate):
+            return candidate
+    return None
+
+
+def update_placeholder(
+    chat_id: str,
+    text: str,
+    *,
+    socket_path: Optional[str] = None,
+    timeout_secs: float = 0.25,
+) -> bool:
+    """Send an `update_placeholder` message to the gateway. Returns True
+    on success (message written), False on any failure.
+
+    Failure cases (all silent):
+      - No socket path resolvable.
+      - Socket connect refused / timeout.
+      - Socket write fails (rare).
+
+    Caller should never branch on the return value — it's purely for
+    test introspection.
+    """
+    if not chat_id or not isinstance(chat_id, str):
+        return False
+    if not text or not isinstance(text, str):
+        return False
+
+    path = socket_path or gateway_socket_path()
+    if path is None:
+        return False
+
+    payload = json.dumps({
+        "type": "update_placeholder",
+        "chatId": chat_id,
+        "text": text,
+    }) + "\n"
+
+    sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+    sock.settimeout(timeout_secs)
+    try:
+        sock.connect(path)
+        sock.sendall(payload.encode("utf-8"))
+        return True
+    except (FileNotFoundError, ConnectionRefusedError, OSError, socket.timeout):
+        return False
+    finally:
+        try:
+            sock.close()
+        except OSError:
+            pass