switchroom 0.12.26 → 0.12.28

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

@@ -0,0 +1,286 @@
+#!/usr/bin/env python3
+"""Auto-retain hook for Stop event.
+
+Port of: agent_end handler in Openclaw index.js
+Adapted for Claude Code hooks (ephemeral process, JSON stdin/stdout).
+
+Flow:
+  1. Read hook input from stdin (session_id, transcript_path, cwd)
+  2. Read conversation transcript from transcript_path
+  3. Apply chunked retention logic (retainEveryNTurns + overlap window)
+  4. Resolve API URL (external, existing local, or auto-start daemon)
+  5. Derive bank ID and ensure mission
+  6. Format transcript (strip memory tags, filter roles)
+  7. POST to Hindsight retain API (async)
+
+Exit codes:
+  0 — always (graceful degradation on any error)
+"""
+
+import json
+import os
+import sys
+import time
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from lib.bank import derive_bank_id, ensure_bank_mission
+from lib.client import HindsightClient
+from lib.config import debug_log, load_config
+from lib.content import (
+    prepare_retention_transcript,
+    slice_last_turns_by_user_boundary,
+)
+from lib.daemon import get_api_url
+from lib.state import increment_turn_count, track_retention
+
+
+def read_transcript(transcript_path: str) -> list:
+    """Read a JSONL transcript file and return list of message dicts.
+
+    Claude Code transcript format nests messages:
+      {type: "user", message: {role: "user", content: "..."}, uuid: "...", ...}
+    Also supports flat format for testing:
+      {role: "user", content: "..."}
+    """
+    if not transcript_path or not os.path.isfile(transcript_path):
+        return []
+    messages = []
+    try:
+        with open(transcript_path, encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    entry = json.loads(line)
+                    # Claude Code nested format: {type: "user", message: {role, content}}
+                    if entry.get("type") in ("user", "assistant"):
+                        msg = entry.get("message", {})
+                        if isinstance(msg, dict) and msg.get("role"):
+                            messages.append(msg)
+                    # Flat format (testing / future compatibility)
+                    elif "role" in entry and "content" in entry:
+                        messages.append(entry)
+                except json.JSONDecodeError:
+                    continue
+    except OSError:
+        pass
+    return messages
+
+
+def run_retain(hook_input: dict, force: bool = False) -> dict:
+    """Run the auto-retain flow.
+
+    Returns a status dict::
+
+        {"status": "ok" | "skipped" | "failed",
+         "payload": {...},   # only when status == "failed"
+         "error":   Exception}  # only when status == "failed"
+
+    The ``payload`` field carries the exact arguments that were going to
+    be sent to ``client.retain()`` plus the resolved ``api_url`` /
+    ``api_token`` — sufficient to retry the call from a different
+    process (the SessionStart drainer, see ``drain_pending.py`` and
+    ``lib/pending.py``). ``status="skipped"`` is the normal early-exit
+    cases (auto-retain disabled, empty transcript, throttled chunk).
+    """
+    config = load_config()
+
+    if not config.get("autoRetain"):
+        debug_log(config, "Auto-retain disabled, exiting")
+        return {"status": "skipped", "reason": "autoRetain disabled"}
+
+    debug_log(config, f"Retain hook_input keys: {list(hook_input.keys())} force={force}")
+
+    session_id = hook_input.get("session_id", "unknown")
+    transcript_path = hook_input.get("transcript_path", "")
+
+    # Read full transcript
+    all_messages = read_transcript(transcript_path)
+    if not all_messages:
+        debug_log(config, "No messages in transcript, skipping retain")
+        return {"status": "skipped", "reason": "empty transcript"}
+
+    debug_log(config, f"Read {len(all_messages)} messages from transcript")
+
+    # Retention mode: full session (default) or chunked (legacy)
+    retain_mode = config.get("retainMode", "full-session")
+    retain_every_n = max(1, config.get("retainEveryNTurns", 1))
+    retain_full_window = False
+    messages_to_retain = all_messages
+
+    # Respect retainEveryNTurns in both modes, unless force=True (SessionEnd final retain)
+    if retain_every_n > 1 and not force:
+        turn_count = increment_turn_count(session_id)
+        if turn_count % retain_every_n != 0:
+            next_at = ((turn_count // retain_every_n) + 1) * retain_every_n
+            debug_log(config, f"Turn {turn_count}/{retain_every_n}, skipping retain (next at turn {next_at})")
+            return {"status": "skipped", "reason": "throttled"}
+
+    if retain_mode == "chunked" and retain_every_n > 1:
+        # Sliding window: N turns + configured overlap
+        overlap_turns = config.get("retainOverlapTurns", 0)
+        window_turns = retain_every_n + overlap_turns
+        messages_to_retain = slice_last_turns_by_user_boundary(all_messages, window_turns)
+        retain_full_window = True
+        debug_log(
+            config,
+            f"Chunked retain firing (window: {window_turns} turns, {len(messages_to_retain)} messages)",
+        )
+    else:
+        # Full session mode: retain all messages, always as full window
+        retain_full_window = True
+        debug_log(config, f"Full session retain: {len(all_messages)} messages")
+
+    # Format transcript
+    retain_roles = config.get("retainRoles", ["user", "assistant"])
+    include_tool_calls = config.get("retainToolCalls", True)
+    transcript, message_count = prepare_retention_transcript(
+        messages_to_retain, retain_roles, retain_full_window, include_tool_calls=include_tool_calls
+    )
+
+    if not transcript:
+        debug_log(config, "Empty transcript after formatting, skipping retain")
+        return {"status": "skipped", "reason": "empty transcript after formatting"}
+
+    # Resolve API URL
+    def _dbg(*a):
+        debug_log(config, *a)
+
+    try:
+        api_url = get_api_url(config, debug_fn=_dbg, allow_daemon_start=True)
+    except RuntimeError as e:
+        print(f"[Hindsight] {e}", file=sys.stderr)
+        return {"status": "failed", "error": e, "payload": None}
+
+    api_token = config.get("hindsightApiToken")
+    try:
+        client = HindsightClient(api_url, api_token)
+    except ValueError as e:
+        print(f"[Hindsight] Invalid API URL: {e}", file=sys.stderr)
+        return {"status": "failed", "error": e, "payload": None}
+
+    # Derive bank ID and ensure mission
+    bank_id = derive_bank_id(hook_input, config)
+    ensure_bank_mission(client, bank_id, config, debug_fn=_dbg)
+
+    # Document ID strategy:
+    # - Chunked mode: each chunk gets a timestamped document_id.
+    # - Full-session mode: uses session_id as base, but tracks message count
+    #   to detect compaction.  When Claude Code compacts the conversation the
+    #   transcript shrinks — if we kept the same document_id we'd overwrite the
+    #   pre-compaction document with a shorter one, losing context.  Instead we
+    #   increment a chunk counter so the old document is preserved.
+    if retain_mode == "chunked" and retain_every_n > 1:
+        document_id = f"{session_id}-{int(time.time() * 1000)}"
+    else:
+        chunk_index, compacted = track_retention(session_id, len(all_messages))
+        if compacted:
+            debug_log(
+                config,
+                f"Compaction detected for session {session_id}: transcript shrank, "
+                f"advancing to chunk {chunk_index} to preserve prior document",
+            )
+        # chunk 0 → plain session_id (backwards compatible with existing docs)
+        document_id = session_id if chunk_index == 0 else f"{session_id}-c{chunk_index}"
+
+    # Resolve template variables in tags and metadata.
+    # Supported variables: {session_id}, {bank_id}, {timestamp}, {user_id}
+    template_vars = {
+        "session_id": session_id,
+        "bank_id": bank_id,
+        "timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        "user_id": os.environ.get("HINDSIGHT_USER_ID", ""),
+    }
+
+    def _resolve_template(value: str) -> str:
+        for k, v in template_vars.items():
+            value = value.replace(f"{{{k}}}", v)
+        return value
+
+    # Tags from config with template resolution.
+    # Drop tags whose resolved form ends in an empty namespace part (e.g. "user:"
+    # when HINDSIGHT_USER_ID is unset). Tags without ':' are preserved as-is.
+    raw_tags = config.get("retainTags", [])
+    if raw_tags:
+        tags = []
+        for original in raw_tags:
+            resolved = _resolve_template(original)
+            if ":" in resolved and resolved.split(":", 1)[1] == "":
+                debug_log(config, f"Dropping tag '{original}' -> '{resolved}' (empty content after ':')")
+                continue
+            tags.append(resolved)
+        if not tags:
+            tags = None
+    else:
+        tags = None
+
+    # Metadata: merge built-in defaults with user-configured extras
+    metadata = {
+        "retained_at": template_vars["timestamp"],
+        "message_count": str(message_count),
+        "session_id": session_id,
+    }
+    for k, v in config.get("retainMetadata", {}).items():
+        metadata[k] = _resolve_template(str(v))
+
+    debug_log(
+        config, f"Retaining to bank '{bank_id}', doc '{document_id}', {message_count} messages, {len(transcript)} chars"
+    )
+    if tags:
+        debug_log(config, f"Tags: {tags}")
+
+    # Build the full payload up-front so we can hand it to the pending-
+    # retains queue verbatim if the POST fails. The payload mirrors the
+    # client.retain() kwargs plus connection info (api_url, api_token)
+    # so the drainer can reconstruct the call from a different process.
+    payload = {
+        "api_url": api_url,
+        "api_token": api_token,
+        "bank_id": bank_id,
+        "content": transcript,
+        "document_id": document_id,
+        "context": config.get("retainContext", "claude-code"),
+        "metadata": metadata,
+        "tags": tags,
+    }
+
+    # POST to Hindsight retain API
+    try:
+        response = client.retain(
+            bank_id=bank_id,
+            content=transcript,
+            document_id=document_id,
+            context=payload["context"],
+            metadata=metadata,
+            tags=tags,
+            timeout=15,
+        )
+        debug_log(config, f"Retain response: {json.dumps(response)[:200]}")
+        return {"status": "ok", "response": response}
+    except Exception as e:
+        print(f"[Hindsight] Retain failed: {e}", file=sys.stderr)
+        return {"status": "failed", "error": e, "payload": payload}
+
+
+def main():
+    try:
+        hook_input = json.load(sys.stdin)
+    except (json.JSONDecodeError, EOFError):
+        print("[Hindsight] Failed to read hook input", file=sys.stderr)
+        return
+    run_retain(hook_input, force=False)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as e:
+        print(f"[Hindsight] Unexpected error in retain: {e}", file=sys.stderr)
+        try:
+            from lib.config import load_config
+
+            sys.exit(2 if load_config().get("debug") else 0)
+        except Exception:
+            sys.exit(0)

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

@@ -0,0 +1,122 @@
+#!/usr/bin/env python3
+"""SessionEnd hook: final retain + daemon cleanup.
+
+Fires once when a Claude Code session terminates. Two jobs:
+
+1. **Final retain.** Forces a retain pass so short sessions (fewer
+   turns than ``retainEveryNTurns``) still land on disk.
+2. **Daemon stop.** Tears down the auto-started hindsight-embed
+   daemon, if any.
+
+Silent data-loss guard (#1071)
+------------------------------
+Before this change the final retain would print its error to stderr
+and exit 0 — the operator sees nothing in journald (already noisy),
+the agent thinks the turn was saved, the *next* session can't recall
+the turn. Silent memory loss.
+
+Now: on retain failure we serialize the full retain payload to
+``~/.hindsight/pending-retains/<unix-ms>-<uuid>.json`` (see
+``lib/pending.py``) and exit non-zero so ``bin/run-hook.sh`` routes
+the failure through the ``switchroom issues`` sink (#424). The next
+SessionStart drains the queue (see ``drain_pending.py``).
+
+Pairs with #1070 (recall.py exit-code fix) — same threat class.
+
+Port of: Openclaw's service.stop() in index.js.
+"""
+
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+from lib.config import debug_log, load_config
+from lib.daemon import stop_daemon
+from lib.pending import MAX_ENTRIES, count as pending_count, enqueue as pending_enqueue
+
+
+# Exit codes:
+#   0 — success (or retain skipped for benign reasons)
+#   1 — retain failed AND was queued to pending-retains (recoverable)
+#   2 — retain failed AND the queue rejected it (chronic backlog)
+EXIT_OK = 0
+EXIT_QUEUED = 1
+EXIT_DROPPED = 2
+
+
+def main() -> int:
+    config = load_config()
+
+    # Consume stdin
+    try:
+        hook_input = json.load(sys.stdin)
+    except (json.JSONDecodeError, EOFError):
+        hook_input = {}
+
+    debug_log(config, f"SessionEnd hook, reason: {hook_input.get('reason', 'unknown')}")
+
+    exit_code = EXIT_OK
+
+    # Force a final retain before stopping the daemon — guarantees short sessions
+    # (fewer turns than retainEveryNTurns) still land on disk.
+    if config.get("autoRetain") and hook_input.get("transcript_path"):
+        try:
+            from retain import run_retain
+
+            result = run_retain(hook_input, force=True) or {}
+        except Exception as e:
+            # Belt-and-braces — run_retain itself shouldn't raise, but
+            # if it does we treat it the same as a failed POST: queue
+            # what we can (nothing, since we have no payload) and exit
+            # non-zero so the issue sink picks it up.
+            print(f"[Hindsight] SessionEnd final retain error: {e}", file=sys.stderr)
+            result = {"status": "failed", "error": e, "payload": None}
+
+        if result.get("status") == "failed":
+            payload = result.get("payload")
+            err = result.get("error") or RuntimeError("unknown retain failure")
+            if payload:
+                queued = pending_enqueue(payload, err)
+                if queued is None:
+                    print(
+                        f"[Hindsight] pending-retains queue full ({MAX_ENTRIES} entries); "
+                        f"dropping this retain. Operator: drain manually, then run "
+                        f"`switchroom doctor`.",
+                        file=sys.stderr,
+                    )
+                    exit_code = EXIT_DROPPED
+                else:
+                    debug_log(config, f"SessionEnd retain queued to {queued} (pending={pending_count()})")
+                    print(
+                        f"[Hindsight] SessionEnd retain failed: queued to pending-retains "
+                        f"(error: {type(err).__name__}: {err}). Will retry on next "
+                        f"SessionStart.",
+                        file=sys.stderr,
+                    )
+                    exit_code = EXIT_QUEUED
+            else:
+                # No payload to queue — the failure happened before we
+                # finished building one (e.g. URL resolution).
+                exit_code = EXIT_QUEUED
+
+    # Stop daemon if we started it. Always runs, even on retain failure,
+    # so we don't leak a daemon process.
+    def _dbg(*a):
+        debug_log(config, *a)
+
+    stop_daemon(config, debug_fn=_dbg)
+    return exit_code
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except Exception as e:
+        print(f"[Hindsight] SessionEnd error: {e}", file=sys.stderr)
+        # Surface the unexpected failure to the issue sink rather than
+        # swallowing it (per #424). Stays non-zero in both debug and
+        # non-debug paths so the recall.py-style silent-failure trap
+        # (#1070) doesn't recur here.
+        sys.exit(2)

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

@@ -0,0 +1,76 @@
+#!/usr/bin/env python3
+"""SessionStart hook: health check + session logging.
+
+Fires once when a Claude Code session begins. Uses additionalContext
+(supported on SessionStart) to inject an initial system note if
+Hindsight is available.
+
+This is the Claude Code equivalent of Openclaw's service.start() —
+verify the server is reachable early, before the first prompt.
+"""
+
+import json
+import os
+import sys
+
+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.daemon import get_api_url, prestart_daemon_background
+
+
+def main():
+    config = load_config()
+
+    if not config.get("autoRecall") and not config.get("autoRetain"):
+        debug_log(config, "Both autoRecall and autoRetain disabled, skipping session start")
+        return
+
+    # Consume stdin
+    try:
+        hook_input = json.load(sys.stdin)
+    except (json.JSONDecodeError, EOFError):
+        hook_input = {}
+
+    debug_log(config, f"SessionStart hook, source: {hook_input.get('source', 'unknown')}")
+
+    # Try to resolve API URL (health check). Don't start daemon here —
+    # that's too slow for session start. Just check if server is reachable.
+    def _dbg(*a):
+        debug_log(config, *a)
+
+    try:
+        api_url = get_api_url(config, debug_fn=_dbg, allow_daemon_start=False)
+        client = HindsightClient(api_url, config.get("hindsightApiToken"))
+        debug_log(config, f"Hindsight server reachable at {api_url}")
+    except (RuntimeError, ValueError) as e:
+        # Server not running — kick off background pre-start so it's ready
+        # by the time the first recall or retain hook fires. Skip the
+        # drain here: with no server to talk to, every retry would just
+        # bump attempt counters and burn the SessionStart budget.
+        debug_log(config, f"Hindsight not running, initiating background pre-start: {e}")
+        prestart_daemon_background(config, debug_fn=_dbg)
+        return
+
+    # Drain any retains that session_end.py queued on failure (#1071).
+    # Bounded by HINDSIGHT_DRAIN_BUDGET_S so a slow upstream can't pin
+    # the SessionStart hook. The drain is best-effort — failures stay
+    # queued for the next session, dead entries surface via
+    # `switchroom doctor`.
+    try:
+        from drain_pending import drain as drain_pending_retains
+
+        drain_pending_retains(config)
+    except Exception as e:
+        # Never let the drain break session start. Issue sink picks
+        # this up via run-hook.sh — see exit-code path in __main__.
+        debug_log(config, f"drain_pending unexpected error (ignored): {e}")
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception as e:
+        print(f"[Hindsight] SessionStart error: {e}", file=sys.stderr)
+        sys.exit(0)

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

@@ -0,0 +1,115 @@
+#!/usr/bin/env python3
+"""Register hindsight-memory hooks into ~/.claude/settings.json.
+
+Claude Code's plugin installer does not currently merge hooks.json into
+settings.json automatically. Run this script once after installing the plugin:
+
+    python3 setup_hooks.py
+
+Or via the /hindsight:setup skill inside a Claude Code session.
+"""
+
+import json
+import os
+import sys
+
+SETTINGS_PATH = os.path.expanduser("~/.claude/settings.json")
+
+
+def find_plugin_root() -> str:
+    """Locate the installed hindsight-memory plugin cache directory."""
+    cache_base = os.path.expanduser("~/.claude/plugins/cache/hindsight/hindsight-memory")
+    if not os.path.isdir(cache_base):
+        raise RuntimeError(
+            "hindsight-memory plugin not found. "
+            "Run /plugin install hindsight-memory inside Claude Code first."
+        )
+    versions = sorted(os.listdir(cache_base), reverse=True)
+    if not versions:
+        raise RuntimeError(f"No versions found in {cache_base}")
+    return os.path.join(cache_base, versions[0])
+
+
+def build_hooks(plugin_root: str) -> dict:
+    return {
+        "UserPromptSubmit": [
+            {
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": f'python3 "{plugin_root}/scripts/recall.py"',
+                        "timeout": 12,
+                    }
+                ]
+            }
+        ],
+        "Stop": [
+            {
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": f'python3 "{plugin_root}/scripts/retain.py"',
+                        "timeout": 15,
+                        "async": True,
+                    }
+                ]
+            }
+        ],
+        "SessionStart": [
+            {
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": f'python3 "{plugin_root}/scripts/session_start.py"',
+                        "timeout": 5,
+                    }
+                ]
+            }
+        ],
+        "SessionEnd": [
+            {
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": f'python3 "{plugin_root}/scripts/session_end.py"',
+                        "timeout": 10,
+                    }
+                ]
+            }
+        ],
+    }
+
+
+def main():
+    try:
+        plugin_root = find_plugin_root()
+    except RuntimeError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    if not os.path.isfile(SETTINGS_PATH):
+        print(f"Error: {SETTINGS_PATH} not found. Is Claude Code installed?", file=sys.stderr)
+        sys.exit(1)
+
+    with open(SETTINGS_PATH) as f:
+        settings = json.load(f)
+
+    existing_hooks = settings.get("hooks", {})
+    if existing_hooks:
+        print("Existing hooks found — merging (hindsight-memory hooks take precedence).")
+
+    new_hooks = build_hooks(plugin_root)
+    merged = {**existing_hooks, **new_hooks}
+    settings["hooks"] = merged
+    settings.setdefault("env", {})["CLAUDE_PLUGIN_ROOT"] = plugin_root
+
+    with open(SETTINGS_PATH, "w") as f:
+        json.dump(settings, f, indent=2)
+
+    print(f"hindsight-memory hooks registered successfully.")
+    print(f"Plugin root: {plugin_root}")
+    print(f"Restart Claude Code for changes to take effect.")
+
+
+if __name__ == "__main__":
+    main()