switchroom 0.12.27 → 0.12.28

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)

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

@@ -0,0 +1,180 @@
+"""Configuration management for Hindsight plugin.
+
+Loads settings from settings.json (plugin defaults) merged with environment
+variable overrides. Full config schema matching Openclaw's 30+ options.
+"""
+
+import json
+import os
+import sys
+
+DEFAULTS = {
+    # Recall
+    "autoRecall": True,
+    # Switchroom default: "low" — vector search only, no LLM reranking.
+    # Cuts the recall hook latency from ~5s (mid budget) to ~1-2s (low).
+    # Operators who want richer recall can set HINDSIGHT_RECALL_BUDGET=mid
+    # via per-agent env or write `recallBudget: "mid"` into the user
+    # config file. Forensics on real klanker turns showed mid-budget
+    # recall was ~5s of wall-clock latency dominated by the LLM filter
+    # pass; for chat-pattern agents the vector hits alone are fine and
+    # the 5s is the second-largest contributor to perceived dead air
+    # (after the model TTFT).
+    "recallBudget": "low",
+    "recallMaxTokens": 1024,
+    # Switchroom-local: cap on the number of memories injected into the
+    # `<hindsight_memories>` block, regardless of token budget. Plugin v0.4.0
+    # exposes `recallTopK` only in the Openclaw integration, not the
+    # Claude Code integration, so we slice client-side in recall.py before
+    # formatting. Set to 0 (or any non-positive value) to disable the cap
+    # and inject everything Hindsight returns.
+    "recallMaxMemories": 12,
+    # Switchroom-local: minimum lexical (Jaccard) overlap between the
+    # user's query terms and a memory's text terms. Memories below this
+    # threshold are dropped before formatting. 0.0 disables the gate
+    # (current behaviour: inject everything Hindsight returns up to the
+    # count cap). Hindsight's HTTP API does not expose similarity
+    # scores, so this is the switchroom-side quality filter — see #475.
+    "recallMinOverlap": 0.0,
+    "recallTypes": ["world", "experience"],
+    "recallContextTurns": 1,
+    "recallMaxQueryChars": 800,
+    "recallRoles": ["user", "assistant"],
+    "recallPromptPreamble": (
+        "Relevant memories from past conversations (prioritize recent when "
+        "conflicting). Only use memories that are directly useful to continue "
+        "this conversation; ignore the rest:"
+    ),
+    # Retain
+    "autoRetain": True,
+    "retainMode": "full-session",
+    "retainRoles": ["user", "assistant"],
+    "retainEveryNTurns": 10,
+    "retainOverlapTurns": 2,
+    "retainToolCalls": True,
+    "retainContext": "claude-code",
+    "retainTags": [],
+    "retainMetadata": {},
+    "recallAdditionalBanks": [],
+    # Connection
+    "hindsightApiUrl": None,
+    "hindsightApiToken": None,
+    "apiPort": 9077,
+    "daemonIdleTimeout": 0,
+    "embedVersion": "latest",
+    "embedPackagePath": None,
+    # Bank
+    "bankId": None,
+    "bankIdPrefix": "",
+    "dynamicBankId": False,
+    "dynamicBankGranularity": ["agent", "project"],
+    "bankMission": "",
+    "retainMission": None,
+    "agentName": "claude-code",
+    # LLM (for daemon mode)
+    "llmProvider": None,
+    "llmModel": None,
+    "llmApiKeyEnv": None,
+    # Misc
+    "debug": False,
+}
+
+# Map env var names to config keys and their types
+ENV_OVERRIDES = {
+    "HINDSIGHT_API_URL": ("hindsightApiUrl", str),
+    "HINDSIGHT_API_TOKEN": ("hindsightApiToken", str),
+    "HINDSIGHT_BANK_ID": ("bankId", str),
+    "HINDSIGHT_AGENT_NAME": ("agentName", str),
+    "HINDSIGHT_AUTO_RECALL": ("autoRecall", bool),
+    "HINDSIGHT_AUTO_RETAIN": ("autoRetain", bool),
+    "HINDSIGHT_RETAIN_MODE": ("retainMode", str),
+    "HINDSIGHT_RECALL_BUDGET": ("recallBudget", str),
+    "HINDSIGHT_RECALL_MAX_TOKENS": ("recallMaxTokens", int),
+    # Switchroom-local: count cap. Set by start.sh from
+    # agents.<name>.memory.recall.max_memories (cascading through
+    # defaults.memory.recall.max_memories) when present in switchroom.yaml.
+    "HINDSIGHT_RECALL_MAX_MEMORIES": ("recallMaxMemories", int),
+    # Switchroom-local: lexical-overlap threshold (#475). Float in
+    # [0.0, 1.0]. Set by start.sh from agents.<name>.memory.recall.min_overlap
+    # (cascading through defaults). 0.0 = off (current behaviour).
+    "HINDSIGHT_RECALL_MIN_OVERLAP": ("recallMinOverlap", float),
+    "HINDSIGHT_RECALL_MAX_QUERY_CHARS": ("recallMaxQueryChars", int),
+    "HINDSIGHT_RECALL_CONTEXT_TURNS": ("recallContextTurns", int),
+    "HINDSIGHT_API_PORT": ("apiPort", int),
+    "HINDSIGHT_DAEMON_IDLE_TIMEOUT": ("daemonIdleTimeout", int),
+    "HINDSIGHT_EMBED_VERSION": ("embedVersion", str),
+    "HINDSIGHT_EMBED_PACKAGE_PATH": ("embedPackagePath", str),
+    "HINDSIGHT_DYNAMIC_BANK_ID": ("dynamicBankId", bool),
+    "HINDSIGHT_BANK_MISSION": ("bankMission", str),
+    "HINDSIGHT_LLM_PROVIDER": ("llmProvider", str),
+    "HINDSIGHT_LLM_MODEL": ("llmModel", str),
+    "HINDSIGHT_DEBUG": ("debug", bool),
+}
+
+
+def _cast_env(value: str, typ):
+    """Cast environment variable string to target type. Returns None on failure."""
+    try:
+        if typ is bool:
+            return value.lower() in ("true", "1", "yes")
+        if typ is int:
+            return int(value)
+        if typ is float:
+            return float(value)
+        return value
+    except (ValueError, AttributeError):
+        return None
+
+
+def _load_settings_file(path: str, config: dict) -> None:
+    """Merge a settings.json file into config in-place. Silently skips if missing."""
+    if not os.path.exists(path):
+        return
+    try:
+        with open(path) as f:
+            file_config = json.load(f)
+        config.update({k: v for k, v in file_config.items() if v is not None})
+    except (json.JSONDecodeError, OSError) as e:
+        debug_log(config, f"Failed to load {path}: {e}")
+
+
+def load_config() -> dict:
+    """Load plugin configuration from settings.json + env overrides.
+
+    Loading order (later entries win):
+      1. Built-in defaults
+      2. Plugin default settings.json  (CLAUDE_PLUGIN_ROOT/settings.json)
+      3. User config                   (~/.hindsight/claude-code.json)
+      4. Environment variable overrides
+
+    ~/.hindsight/claude-code.json is the recommended place to configure the
+    plugin — same convention as ~/.openclaw/openclaw.json. It is stable across
+    plugin updates and marketplace changes.
+    """
+    config = dict(DEFAULTS)
+
+    # 1. Plugin default settings.json (ships with the plugin, version-specific path)
+    plugin_root = os.environ.get("CLAUDE_PLUGIN_ROOT", "")
+    if not plugin_root:
+        plugin_root = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+    _load_settings_file(os.path.join(plugin_root, "settings.json"), config)
+
+    # 2. User config — stable, version-independent, matches openclaw convention
+    user_config_path = os.path.join(os.path.expanduser("~"), ".hindsight", "claude-code.json")
+    _load_settings_file(user_config_path, config)
+
+    # Apply environment variable overrides
+    for env_name, (key, typ) in ENV_OVERRIDES.items():
+        val = os.environ.get(env_name)
+        if val is not None:
+            cast_val = _cast_env(val, typ)
+            if cast_val is not None:
+                config[key] = cast_val
+
+    return config
+
+
+def debug_log(config: dict, *args):
+    """Log to stderr if debug mode is enabled."""
+    if config.get("debug"):
+        print("[Hindsight]", *args, file=sys.stderr)