@gamaze/hicortex 0.12.1 → 0.13.1

package/hermes-plugin/hicortex/provider.py

@@ -16,8 +16,11 @@ from __future__ import annotations
 import hashlib
 import json
 import logging
+import os
+import re
 import threading
-from typing import Any, Dict, List, Optional
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, Dict, Iterable, List, Optional
 
 from agent.memory_provider import MemoryProvider
 
@@ -28,6 +31,89 @@ logger = logging.getLogger(__name__)
 
 _INJECT_CONTENT_CAP = 500
 
+# Agent ids are joined into a filesystem path server-side, so they share the
+# section-name allowlist. \Z (NOT $) anchors the END OF STRING: Python's $ also
+# matches just before a trailing "\n", so "nano\n" would pass and go out as
+# agent=nano%0A → a 400 the fail-soft path silently swallows.
+_AGENT_ID_RE = re.compile(r"^[a-z0-9][a-z0-9_-]*\Z")
+
+
+def _valid_agent_id(name: Optional[str]) -> bool:
+    return bool(name) and len(name) <= 64 and bool(_AGENT_ID_RE.match(name))
+
+
+def _sanitize_agent_id(raw: Optional[str]) -> Optional[str]:
+    """Sanitize a raw identity (profile name / env value) into a valid agent id,
+    or None when nothing valid remains — mirrors the TS ``sanitizeAgentId``
+    EXACTLY so a profile resolves to the SAME id on both harnesses (a mismatch
+    would make one honor the persona firewall and the other leak global context
+    into an ``off``/``override`` persona): lowercase → collapse invalid runs to
+    "-" → strip leading -/_ → truncate 64 → validate. "Lenny" → "lenny";
+    "MacBook-Pro.local" → "macbook-pro-local"; all-symbols → None."""
+    if not isinstance(raw, str):
+        return None
+    cleaned = re.sub(r"[^a-z0-9_-]+", "-", raw.lower())
+    cleaned = re.sub(r"^[-_]+", "", cleaned)[:64]
+    return cleaned if _valid_agent_id(cleaned) else None
+
+
+def _profile_from_home(home: str) -> Optional[str]:
+    """Parse a Hermes profile name from a ``HERMES_HOME`` ending in
+    ``…/profiles/<name>``; None when the path is not profile-shaped."""
+    home = (home or "").strip().rstrip("/")
+    if not home:
+        return None
+    parent, name = os.path.split(home)
+    return name if name and os.path.basename(parent) == "profiles" else None
+
+
+def _resolve_agent_name(cfg: Dict[str, Any]) -> Optional[str]:
+    """Resolve the per-agent context id (0.13), in priority order:
+      1. config ``agent_name`` (explicit override);
+      2. ``HERMES_PROFILE`` env;
+      3. parse ``HERMES_HOME`` when it ends ``profiles/<name>``;
+      4. None → bare fetch → the global set.
+    Each source is stripped then SANITIZED (not rejected) so "Lenny" → "lenny"
+    matches the TS contract; a source that sanitizes to None yields None (bare
+    fetch), never a fall-through to another identity."""
+    configured = (cfg.get("agent_name") or "").strip()
+    if configured:
+        return _sanitize_agent_id(configured)
+    prof = (os.environ.get("HERMES_PROFILE") or "").strip()
+    if prof:
+        return _sanitize_agent_id(prof)
+    parsed = _profile_from_home(os.environ.get("HERMES_HOME") or "")
+    if parsed:
+        return _sanitize_agent_id(parsed)
+    return None
+
+
+def _title_case_section(name: str) -> str:
+    """"user" → "User", "my_notes" → "My Notes" (mirrors the CC/OC helper)."""
+    words = [w for w in re.split(r"[-_]+", name) if w]
+    return " ".join(w[:1].upper() + w[1:] for w in words)
+
+
+def _order_section_names(names: Iterable[str]) -> List[str]:
+    """Stable ordering: user, rules, then the rest alphabetically."""
+    names = list(names)
+    primaries = [p for p in ("user", "rules") if p in names]
+    rest = sorted(n for n in names if n not in ("user", "rules"))
+    return primaries + rest
+
+
+def _render_context_block(sections: Dict[str, Any]) -> str:
+    """Render the ``## Context`` block, or "" when every section is blank."""
+    body_parts: List[str] = []
+    for name in _order_section_names(sections.keys()):
+        body = sections.get(name)
+        if not isinstance(body, str) or not body.strip():
+            continue
+        body_parts.extend([f"### {_title_case_section(name)}", "", body.strip()])
+    if not body_parts:
+        return ""
+    return "\n".join(["## Context", "", *body_parts])
+
 
 class HicortexProvider(MemoryProvider):
     """Hicortex long-term memory backend for Hermes (recall-only)."""
@@ -37,6 +123,7 @@ class HicortexProvider(MemoryProvider):
         self._project: Optional[str] = None
         self._recall_limit: int = 5
         self._privacy: Optional[str] = "WORK,PERSONAL"
+        self._agent_name: Optional[str] = None
         self._prefetch_cache: Dict[str, str] = {}
         self._bg_threads: List[threading.Thread] = []
 
@@ -81,6 +168,7 @@ class HicortexProvider(MemoryProvider):
         except (TypeError, ValueError):
             self._recall_limit = 5
         self._privacy = cfg.get("privacy_filter", "WORK,PERSONAL")
+        self._agent_name = _resolve_agent_name(cfg)
         try:
             self._client = self._build_client()
         except Exception as e:
@@ -142,6 +230,51 @@ class HicortexProvider(MemoryProvider):
         client = self._client_or_none()
         if client is None:
             return ""
+        # Standing context (L2, 0.13) is prepended ABOVE the lessons block. The
+        # two fetches run CONCURRENTLY (matching the TS Promise.all paths): run
+        # serially, a blackholed server would stall the turn for up to 2× the
+        # client timeout. Each block fails soft independently — a context failure
+        # must never cost the lessons block, and vice versa.
+        with ThreadPoolExecutor(max_workers=2) as executor:
+            f_context = executor.submit(self._context_block, client)
+            f_lessons = executor.submit(self._lessons_block, client)
+            blocks = [f_context.result(), f_lessons.result()]
+        return "\n\n".join(b for b in blocks if b)
+
+    def _context_block(self, client: HicortexClient) -> str:
+        """Fetch the standing context layer and render a ``## Context`` block,
+        or "" when nothing should be injected. Gates (ALL): "hermes" in the
+        server-resolved ``clients``; when an agent id was SENT, the response
+        echoes ``agent`` (old-server guard — a pre-0.13 server ignores ?agent=
+        and returns global with no echo; injecting would push global context
+        into every persona; the check is skipped on a bare fetch); and the
+        resolved section set is non-empty (mode "off" → {}).
+
+        Reference implementation for the gate: TS ``gateAndRenderContext`` in
+        ``packages/hicortex/src/lessons-context.ts`` (keep the two in sync).
+
+        The ENTIRE path — fetch, parse, gate, render — is inside the try: a
+        malformed ``clients`` value (e.g. an int from a proxy error page) would
+        otherwise raise during the ``in`` check, escape, and cost the lessons
+        block too (mirrors the TS ``.catch(() => null)`` totality)."""
+        try:
+            data = client.context(agent=self._agent_name)
+            if not isinstance(data, dict):
+                return ""
+            clients = data.get("clients") or []
+            if "hermes" not in clients:
+                return ""
+            if self._agent_name is not None and not isinstance(data.get("agent"), str):
+                return ""
+            sections = data.get("sections") or {}
+            if not isinstance(sections, dict):
+                return ""
+            return _render_context_block(sections)
+        except Exception as e:
+            logger.debug("hicortex context injection failed: %s", e)
+            return ""
+
+    def _lessons_block(self, client: HicortexClient) -> str:
         try:
             data = client.lessons()
         except Exception as e:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gamaze/hicortex",
-  "version": "0.12.1",
+  "version": "0.13.1",
   "description": "Self-learning memory for AI agents \u2014 experience captured automatically, distilled into lessons overnight, shared across your whole fleet. Works with Hermes, OpenClaw, Claude Code, and Pi.",
   "main": "dist/index.js",
   "bin": {