switchroom 0.12.26 → 0.12.28

package/vendor/hindsight-memory/scripts/drain_pending.py

@@ -0,0 +1,190 @@
+#!/usr/bin/env python3
+"""Drain ``~/.hindsight/pending-retains/``.
+
+SessionStart calls into ``drain()`` to retry any retain payloads that
+``session_end.py`` queued on failure (#1071). Each entry is retried up
+to ``MAX_ATTEMPTS`` (5) times; after that it's renamed to ``.dead`` so
+the queue no longer drains it but the operator can still inspect via
+``switchroom doctor``.
+
+Boundaries
+----------
+* Per-entry HTTP timeout: ``HINDSIGHT_DRAIN_TIMEOUT`` (default 5s).
+* Stall guard: if ``STALL_THRESHOLD`` (3) consecutive entries fail with
+  the same error class, we stop draining for this session — that's a
+  systemic outage, not a transient flake, and continuing would only
+  burn the SessionStart timeout budget. The remaining entries stay
+  queued for the next session.
+* Total wall-clock cap: ``HINDSIGHT_DRAIN_BUDGET_S`` (default 4s) so
+  drain never blocks SessionStart longer than the upstream
+  hook timeout permits.
+
+Standalone usage::
+
+    python3 drain_pending.py        # one-shot drain, prints summary
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import time
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from lib.client import HindsightClient
+from lib.config import debug_log, load_config
+from lib.pending import (
+    MAX_ATTEMPTS,
+    delete_entry,
+    iter_entries,
+    mark_dead,
+    update_attempt,
+)
+
+
+STALL_THRESHOLD = 3
+
+
+def _per_entry_timeout() -> int:
+    raw = os.environ.get("HINDSIGHT_DRAIN_TIMEOUT", "5")
+    try:
+        v = int(raw)
+        return max(1, v)
+    except ValueError:
+        return 5
+
+
+def _budget_seconds() -> float:
+    raw = os.environ.get("HINDSIGHT_DRAIN_BUDGET_S", "4")
+    try:
+        v = float(raw)
+        return max(0.5, v)
+    except ValueError:
+        return 4.0
+
+
+def _retry_one(entry: dict, timeout: int) -> None:
+    """POST a single queued retain. Raises on failure."""
+    client = HindsightClient(entry["api_url"], entry.get("api_token"))
+    client.retain(
+        bank_id=entry["bank_id"],
+        content=entry["content"],
+        document_id=entry.get("document_id", "conversation"),
+        context=entry.get("context"),
+        metadata=entry.get("metadata") or {},
+        tags=entry.get("tags"),
+        timeout=timeout,
+    )
+
+
+def drain(config: dict | None = None) -> dict:
+    """Walk the pending-retains directory and retry each entry.
+
+    Returns a summary dict::
+
+        {"drained": int,   # successful retries (entries deleted)
+         "retried": int,   # failures kept for next session
+         "dead":    int,   # entries promoted to .dead this run
+         "stalled": bool,  # stall guard tripped
+         "budget_exceeded": bool}
+    """
+    config = config or load_config()
+    timeout = _per_entry_timeout()
+    budget = _budget_seconds()
+    started = time.monotonic()
+
+    summary = {
+        "drained": 0,
+        "retried": 0,
+        "dead": 0,
+        "stalled": False,
+        "budget_exceeded": False,
+    }
+
+    entries = iter_entries()
+    if not entries:
+        debug_log(config, "drain_pending: queue empty")
+        return summary
+
+    debug_log(config, f"drain_pending: {len(entries)} entries to retry")
+
+    consecutive_failures = 0
+    last_error_class: str | None = None
+
+    for path, entry in entries:
+        if time.monotonic() - started > budget:
+            summary["budget_exceeded"] = True
+            debug_log(config, "drain_pending: total budget exceeded, stopping")
+            break
+
+        try:
+            _retry_one(entry, timeout=timeout)
+        except Exception as e:
+            err_class = type(e).__name__
+            if err_class == last_error_class:
+                consecutive_failures += 1
+            else:
+                consecutive_failures = 1
+                last_error_class = err_class
+
+            attempts = int(entry.get("attempt_count", 1))
+            if attempts >= MAX_ATTEMPTS:
+                marker = mark_dead(path, entry)
+                summary["dead"] += 1
+                print(
+                    f"[Hindsight] drain_pending: entry exceeded {MAX_ATTEMPTS} "
+                    f"attempts, marking dead at {marker} (last error: {err_class}: {e})",
+                    file=sys.stderr,
+                )
+            else:
+                update_attempt(path, entry, e)
+                summary["retried"] += 1
+                debug_log(
+                    config,
+                    f"drain_pending: retry {attempts}/{MAX_ATTEMPTS} failed for {path} ({err_class}: {e})",
+                )
+
+            if consecutive_failures >= STALL_THRESHOLD:
+                summary["stalled"] = True
+                print(
+                    f"[Hindsight] drain_pending: {consecutive_failures} consecutive "
+                    f"failures with {err_class}, stalling drain. Remaining entries "
+                    f"stay queued.",
+                    file=sys.stderr,
+                )
+                break
+            continue
+
+        # Success — delete the entry.
+        delete_entry(path)
+        summary["drained"] += 1
+        consecutive_failures = 0
+        last_error_class = None
+
+    return summary
+
+
+def main() -> int:
+    config = load_config()
+    summary = drain(config)
+    if summary["drained"] or summary["retried"] or summary["dead"]:
+        print(
+            f"[Hindsight] drain_pending: "
+            f"drained={summary['drained']} retried={summary['retried']} "
+            f"dead={summary['dead']} "
+            f"stalled={summary['stalled']} budget_exceeded={summary['budget_exceeded']}",
+            file=sys.stderr,
+        )
+    # Non-zero only when we promoted entries to .dead — that's the
+    # operator-visible signal. Plain retry-still-pending isn't an error,
+    # the next SessionStart picks them up.
+    return 1 if summary["dead"] else 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except Exception as e:
+        print(f"[Hindsight] drain_pending unexpected error: {e}", file=sys.stderr)
+        sys.exit(2)

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

@@ -0,0 +1,122 @@
+"""Bank ID derivation and mission management.
+
+Port of Openclaw's deriveBankId() and banksWithMissionSet logic, adapted
+for Claude Code's context model.
+
+Openclaw derives bank IDs from: agent, channel, user, provider.
+Claude Code equivalent dimensions:
+  - agent   → configured name or "claude-code" (HINDSIGHT_AGENT_NAME)
+  - project → derived from cwd (working directory basename)
+  - session → session_id from hook input
+  - channel → from env var HINDSIGHT_CHANNEL_ID (for Telegram/Discord agents)
+  - user    → from env var HINDSIGHT_USER_ID (for multi-user agents)
+
+The channel/user dimensions enable the same per-user/per-channel isolation
+that Openclaw provides via its messageProvider/channelId/senderId context.
+Telegram/Discord agents set HINDSIGHT_CHANNEL_ID and HINDSIGHT_USER_ID in
+their environment to achieve equivalent behavior.
+"""
+
+import os
+import sys
+
+from .state import read_state, write_state
+
+DEFAULT_BANK_NAME = "claude-code"
+
+# Valid granularity fields for Claude Code
+VALID_FIELDS = {"agent", "project", "session", "channel", "user"}
+
+
+def derive_bank_id(hook_input: dict, config: dict) -> str:
+    """Derive a bank ID from hook context and config.
+
+    Port of: deriveBankId() in index.js
+
+    When dynamicBankId is false, returns the static bank.
+    When true, composes from granularity fields joined by '::'.
+
+    Args:
+        hook_input: The hook's stdin JSON (has session_id, cwd).
+        config: Plugin configuration dict.
+    """
+    prefix = config.get("bankIdPrefix", "")
+
+    if not config.get("dynamicBankId", False):
+        # Static mode — single bank for everything
+        base = config.get("bankId") or DEFAULT_BANK_NAME
+        return f"{prefix}-{base}" if prefix else base
+
+    # Dynamic mode — compose from granularity fields
+    fields = config.get("dynamicBankGranularity")
+    if not fields or not isinstance(fields, list):
+        fields = ["agent", "project"]
+
+    # Warn on unknown fields (mirrors Openclaw's runtime check)
+    for f in fields:
+        if f not in VALID_FIELDS:
+            print(
+                f'[Hindsight] Unknown dynamicBankGranularity field "{f}" — '
+                f"valid for Claude Code: {', '.join(sorted(VALID_FIELDS))}",
+                file=sys.stderr,
+            )
+
+    # Build field values from hook context + env vars
+    cwd = hook_input.get("cwd", "")
+    session_id = hook_input.get("session_id", "")
+    agent_name = config.get("agentName", "claude-code")
+
+    # Channel and user come from environment variables, set by the host agent
+    # (e.g. Telegram bot sets HINDSIGHT_CHANNEL_ID=telegram-group-12345)
+    channel_id = os.environ.get("HINDSIGHT_CHANNEL_ID", "")
+    user_id = os.environ.get("HINDSIGHT_USER_ID", "")
+
+    field_map = {
+        "agent": agent_name,
+        "project": os.path.basename(cwd) if cwd else "unknown",
+        "session": session_id or "unknown",
+        "channel": channel_id or "default",
+        "user": user_id or "anonymous",
+    }
+
+    # bank_id is stored as-is server-side; HTTP path encoding is the client layer's job.
+    segments = [field_map.get(f, "unknown") for f in fields]
+    base_bank_id = "::".join(segments)
+
+    return f"{prefix}-{base_bank_id}" if prefix else base_bank_id
+
+
+def ensure_bank_mission(client, bank_id: str, config: dict, debug_fn=None):
+    """Set bank mission on first use, skip if already set.
+
+    Port of: banksWithMissionSet Set tracking in index.js
+
+    Uses a state file to persist which banks have had their mission set
+    across ephemeral hook invocations.
+    """
+    mission = config.get("bankMission", "")
+    if not mission or not mission.strip():
+        return
+
+    # Check if we've already set mission for this bank
+    missions_set = read_state("bank_missions.json", {})
+    if bank_id in missions_set:
+        return
+
+    try:
+        retain_mission = config.get("retainMission")
+        client.set_bank_mission(bank_id, mission, retain_mission=retain_mission, timeout=10)
+        missions_set[bank_id] = True
+        # Cap tracked banks (mirrors Openclaw's MAX_TRACKED_BANK_CLIENTS)
+        if len(missions_set) > 10000:
+            keys = sorted(missions_set.keys())
+            for k in keys[: len(keys) // 2]:
+                del missions_set[k]
+        write_state("bank_missions.json", missions_set)
+        if debug_fn:
+            debug_fn(f"Set mission for bank: {bank_id}")
+    except Exception as e:
+        # Don't fail if mission set fails — bank might not exist yet,
+        # will be created on first retain (mirrors Openclaw behavior)
+        if debug_fn:
+            debug_fn(f"Could not set bank mission for {bank_id}: {e}")

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

@@ -0,0 +1,204 @@
+"""Hindsight REST API client.
+
+Communicates with a Hindsight server via HTTP. Mirrors the HTTP mode of the
+Openclaw HindsightClient (client.js), adapted for Python stdlib.
+"""
+
+import json
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+from typing import Optional
+
+DEFAULT_TIMEOUT = 15  # seconds
+HEALTH_CHECK_RETRIES = 3
+HEALTH_CHECK_DELAY = 2  # seconds
+
+
+def _plugin_version() -> str:
+    """Read the plugin version from plugin.json (single source of truth)."""
+    manifest = Path(__file__).resolve().parents[2] / ".claude-plugin" / "plugin.json"
+    try:
+        return json.loads(manifest.read_text()).get("version", "0.0.0")
+    except (OSError, ValueError):
+        return "0.0.0"
+
+
+# Sent on every request so self-hosted deployments behind Cloudflare (or any
+# reverse proxy with UA-based bot filtering) don't block the stdlib default
+# "Python-urllib/X.Y", which trips Cloudflare error 1010.
+USER_AGENT = f"hindsight-claude-code/{_plugin_version()}"
+
+
+def _validate_api_url(url: str) -> str:
+    """Validate and normalize the API URL. Reject non-HTTP schemes."""
+    parsed = urllib.parse.urlparse(url)
+    if parsed.scheme not in ("http", "https"):
+        raise ValueError(f"Hindsight API URL must use http or https, got: {parsed.scheme!r}")
+    if not parsed.hostname:
+        raise ValueError(f"Hindsight API URL has no hostname: {url!r}")
+    return url.rstrip("/")
+
+
+class HindsightClient:
+    """HTTP client for the Hindsight API."""
+
+    def __init__(self, api_url: str, api_token: Optional[str] = None):
+        self.api_url = _validate_api_url(api_url)
+        self.api_token = api_token
+
+    def _headers(self) -> dict:
+        headers = {
+            "Content-Type": "application/json",
+            "User-Agent": USER_AGENT,
+        }
+        if self.api_token:
+            headers["Authorization"] = f"Bearer {self.api_token}"
+        return headers
+
+    def _request(self, method: str, path: str, body: Optional[dict] = None, timeout: int = DEFAULT_TIMEOUT) -> dict:
+        url = f"{self.api_url}{path}"
+        data = json.dumps(body).encode() if body else None
+        req = urllib.request.Request(url, data=data, headers=self._headers(), method=method)
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as resp:
+                return json.loads(resp.read().decode())
+        except urllib.error.HTTPError as e:
+            body_text = ""
+            try:
+                body_text = e.read().decode()
+            except Exception:
+                pass
+            raise RuntimeError(f"HTTP {e.code} from {url}: {body_text}") from e
+
+    def health_check(self, timeout: int = 5) -> bool:
+        """Check if the Hindsight server is reachable.
+
+        Mirrors Openclaw's checkExternalApiHealth: retries up to 3 times
+        with 2s delay between attempts.
+        """
+        import time
+
+        for attempt in range(1, HEALTH_CHECK_RETRIES + 1):
+            try:
+                url = f"{self.api_url}/health"
+                req = urllib.request.Request(url, headers=self._headers(), method="GET")
+                with urllib.request.urlopen(req, timeout=timeout) as resp:
+                    if resp.status == 200:
+                        return True
+            except Exception:
+                pass
+            if attempt < HEALTH_CHECK_RETRIES:
+                time.sleep(HEALTH_CHECK_DELAY)
+        return False
+
+    def recall(
+        self,
+        bank_id: str,
+        query: str,
+        max_tokens: int = 1024,
+        budget: str = "mid",
+        types: Optional[list] = None,
+        timeout: int = 10,
+    ) -> dict:
+        """Recall memories from a bank.
+
+        Returns the raw API response dict with 'results' list.
+        """
+        path = f"/v1/default/banks/{urllib.parse.quote(bank_id, safe='')}/memories/recall"
+        body = {
+            "query": query,
+            "max_tokens": max_tokens,
+        }
+        if budget:
+            body["budget"] = budget
+        if types:
+            body["types"] = types
+        return self._request("POST", path, body, timeout=timeout)
+
+    def retain(
+        self,
+        bank_id: str,
+        content: str,
+        document_id: str = "conversation",
+        context: Optional[str] = None,
+        metadata: Optional[dict] = None,
+        tags: Optional[list] = None,
+        timeout: int = 15,
+    ) -> dict:
+        """Retain content into a bank's memory.
+
+        Posts with async=true so the server processes in the background.
+        The context field helps Hindsight cluster memories by provenance
+        (e.g. "claude-code" vs manual retains).
+        """
+        path = f"/v1/default/banks/{urllib.parse.quote(bank_id, safe='')}/memories"
+        item = {
+            "content": content,
+            "document_id": document_id,
+            "metadata": metadata or {},
+        }
+        if context:
+            item["context"] = context
+        if tags:
+            item["tags"] = tags
+        body = {
+            "items": [item],
+            "async": True,
+        }
+        return self._request("POST", path, body, timeout=timeout)
+
+    def list_directives(
+        self,
+        bank_id: str,
+        active_only: bool = True,
+        tags: Optional[list] = None,
+        timeout: int = 5,
+    ) -> dict:
+        """List active directives for a bank.
+
+        Switchroom-local: this method was missing in the vendored
+        HindsightClient even though `lib/directives.py` (also
+        switchroom-local, the workaround for upstream
+        vectorize-io/hindsight#1269) calls it on every recall hook.
+        Without this method the directives fetch always raised
+        AttributeError → silently caught at directives.py:47-49 → no
+        directives ever surfaced in the recall block.
+
+        The upstream REST endpoint is `GET
+        /v1/default/banks/{bank_id}/directives` with `active_only` and
+        optional `tags` query params (see upstream
+        `hindsight-clients/python/hindsight_client_api/api/directives_api.py`).
+
+        Returns the raw response dict, expected to have an `items` list
+        of directives where each item has at least `id`, `name`,
+        `content`, `priority`, `is_active`, `tags`. Caller (directives.py)
+        already defends against missing/malformed entries.
+        """
+        params = {}
+        if active_only:
+            # Server expects lowercase string per the OpenAPI spec.
+            params["active_only"] = "true"
+        if tags:
+            # Hindsight accepts repeated `tags=` query params for
+            # multi-tag filtering. urlencode with doseq=True handles it.
+            params["tags"] = tags
+        path = f"/v1/default/banks/{urllib.parse.quote(bank_id, safe='')}/directives"
+        if params:
+            path = f"{path}?{urllib.parse.urlencode(params, doseq=True)}"
+        return self._request("GET", path, timeout=timeout)
+
+    def set_bank_mission(
+        self, bank_id: str, mission: str, retain_mission: Optional[str] = None, timeout: int = 15
+    ) -> dict:
+        """Set the mission/persona for a bank.
+
+        Uses PATCH /banks/{id}/config with reflect_mission and retain_mission.
+        The old PUT /banks/{id} with 'mission' field is deprecated in v0.4.19.
+        """
+        path = f"/v1/default/banks/{urllib.parse.quote(bank_id, safe='')}/config"
+        updates = {"reflect_mission": mission}
+        if retain_mission:
+            updates["retain_mission"] = retain_mission
+        return self._request("PATCH", path, {"updates": updates}, timeout=timeout)