claude-smart 0.2.30 → 0.2.32

package/plugin/src/claude_smart/hook_log.py

@@ -0,0 +1,301 @@
+"""Structured, append-only log of every hook fire and its outcome.
+
+Why a dedicated log rather than relying on the Python ``logging`` module:
+hooks run as short-lived subprocesses with no preconfigured handler, so
+``_LOGGER.warning(...)`` calls silently vanish to stderr that Claude Code
+captures but typically does not surface. The dispatcher already wraps
+handlers in a broad ``except`` (so a hook crash never breaks the user's
+session) — without a forensic trail the silent-fail mode is invisible.
+
+This module writes one JSON line per hook fire to
+``~/.claude-smart/hook.log`` from ``hook.main`` after the handler returns.
+The Stop and SessionEnd handlers additionally piggyback their publish
+outcome into the record so the chain hook→adapter→backend is fully
+observable from a single file.
+
+Failure policy: every public function in this module swallows all
+``OSError``/``Exception`` paths. Logging is best-effort; a stuck disk
+or read-only ``$HOME`` must never abort an in-progress hook.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import logging
+import os
+import time
+from collections.abc import Iterator
+from pathlib import Path
+from typing import IO, Any
+
+# ``fcntl`` is POSIX-only. On Windows we skip the cross-process lock and
+# accept the unlikely rotation race (claude-smart is primarily a POSIX
+# tool for Claude Code's plugin runtime).
+try:
+    import fcntl as _fcntl
+except ImportError:  # pragma: no cover — exercised on Windows only
+    _fcntl = None  # type: ignore[assignment]
+
+_LOGGER = logging.getLogger(__name__)
+
+# Anchored on $HOME so unit tests can monkeypatch ``_LOG_PATH`` to a
+# tmp_path. The directory is created lazily on first write — keeping
+# import side-effect-free matches the rest of the package.
+_LOG_PATH = Path.home() / ".claude-smart" / "hook.log"
+
+_TRUNCATE_LIMIT = 4096
+
+# Hard cap on ``hook.log`` size. At ~400 bytes/line and ~50 lines per
+# typical session, 5 MB ≈ 12k records ≈ a few hundred sessions of recent
+# forensic history — enough to debug the last week, bounded so a power
+# user's log can't grow unbounded.
+_MAX_LOG_BYTES = 5 * 1024 * 1024
+
+
+def log_event(
+    *,
+    event: str,
+    host: str,
+    session_id: Any = None,
+    project_id: Any = None,
+    cwd: Any = None,
+    internal_skipped: bool = False,
+    handler_status: str = "ok",
+    publish_status: str | None = None,
+    publish_count: int | None = None,
+    extra: dict[str, Any] | None = None,
+) -> None:
+    """Append one JSON record describing a hook fire.
+
+    Args:
+        event (str): Hook event name (``"stop"``, ``"user-prompt"``, …).
+        host (str): Host identifier (``"claude-code"`` / ``"codex"``).
+        session_id (Any): Claude Code session id from the payload, or
+            ``None`` when the payload didn't carry one.
+        project_id (Any): Project-id resolved from ``cwd``. Optional.
+        cwd (Any): Working directory reported by the hook payload.
+            Optional — preserved verbatim so a future audit can correlate
+            fires against workspace directories.
+        internal_skipped (bool): True when ``is_internal_invocation``
+            short-circuited the dispatcher (reflexio-internal sub-claude
+            calls, or invocations from inside the reflexio submodule).
+        handler_status (str): ``"ok"`` for a clean return, ``"unknown_event"``
+            when no handler is registered, or ``"raised:<ExcClass>: <msg>"``
+            when the handler raised — formatted by ``hook.main``.
+        publish_status (str | None): Status returned by
+            ``publish.publish_unpublished`` (``"ok"`` / ``"failed"`` /
+            ``"nothing"``). Only emitted by Stop + SessionEnd.
+        publish_count (int | None): Interaction count from the same
+            tuple. ``None`` when the handler doesn't publish.
+        extra (dict[str, Any] | None): Free-form fields preserved as-is.
+
+    Returns:
+        None
+    """
+    record: dict[str, Any] = {
+        "ts": int(time.time()),
+        "event": event,
+        "host": host,
+        "session_id": _truncate(session_id),
+        "project_id": _truncate(project_id),
+        "cwd": _truncate(cwd),
+        "internal_skipped": bool(internal_skipped),
+        "handler_status": _truncate(handler_status),
+    }
+    if publish_status is not None:
+        record["publish_status"] = publish_status
+        try:
+            record["publish_count"] = int(
+                publish_count if publish_count is not None else 0
+            )
+        except (TypeError, ValueError):
+            # Defensive: a hostile caller passing an unparseable publish_count
+            # must not abort the hook fire. Treat as zero, the record still
+            # writes with publish_status preserved.
+            record["publish_count"] = 0
+    if extra:
+        for key, value in extra.items():
+            if key in record:
+                continue
+            record[key] = _truncate(value)
+
+    try:
+        line = json.dumps(record, ensure_ascii=False, default=str) + "\n"
+    except (TypeError, ValueError) as exc:
+        _LOGGER.debug("hook_log: json encode failed: %s", exc)
+        return
+
+    path = log_path()
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        _LOGGER.debug("hook_log: mkdir for %s failed: %s", path.parent, exc)
+        return
+
+    # Hold an exclusive cross-process flock through the entire append +
+    # rotate critical section. The original rationale ("POSIX atomic
+    # append below PIPE_BUF") protects the *append* alone but not the
+    # ``read_bytes → write tmp → rename`` rotation sequence: a concurrent
+    # appender that lands between rotation's read and rename has its
+    # record silently dropped by the rename. The lock closes that gap.
+    #
+    # On Windows ``_fcntl`` is None and writes proceed unlocked — same
+    # behaviour as before. The original PIPE_BUF-based append atomicity
+    # is preserved by ``_TRUNCATE_LIMIT`` keeping each record below 4 KiB.
+    with _rotation_lock(path):
+        try:
+            with path.open("a", encoding="utf-8") as fh:
+                fh.write(line)
+        except OSError as exc:
+            _LOGGER.debug("hook_log: write to %s failed: %s", path, exc)
+            return
+
+        # Rotate AFTER the append so the just-written record always survives,
+        # even on the call that crosses the cap. A single oversized record
+        # still gets through and is dropped by the *next* rotation when the
+        # file is read back.
+        _maybe_rotate(path)
+
+
+def log_path() -> Path:
+    """Return the active log path, honouring ``CLAUDE_SMART_HOOK_LOG``.
+
+    Resolution order:
+
+    1. ``CLAUDE_SMART_HOOK_LOG`` env var — escape hatch for tests and
+       advanced users who want the log elsewhere.
+    2. ``_LOG_PATH`` module attribute — what monkeypatched tests override.
+    3. ``~/.claude-smart/hook.log`` — the default.
+
+    Returns:
+        Path: The absolute path to write to.
+    """
+    override = os.environ.get("CLAUDE_SMART_HOOK_LOG")
+    if override:
+        return Path(override)
+    return _LOG_PATH
+
+
+def _truncate(value: Any) -> Any:
+    """Cap string values to ``_TRUNCATE_LIMIT`` chars so single-line writes
+    stay below the POSIX atomic-append limit.
+
+    Non-string values pass through unchanged; the json encoder handles
+    them. ``None`` becomes ``null`` in the JSON, which is what we want.
+    """
+    if isinstance(value, str) and len(value) > _TRUNCATE_LIMIT:
+        return value[:_TRUNCATE_LIMIT] + "…"
+    return value
+
+
+@contextlib.contextmanager
+def _rotation_lock(path: Path) -> Iterator[None]:
+    """Hold an exclusive cross-process flock on a sibling ``.lock`` file.
+
+    Serialises every ``log_event`` call against itself so the rotation
+    ``read_bytes → write tmp → rename`` sequence cannot interleave with a
+    concurrent append. On Windows or when the lock cannot be acquired
+    (no ``fcntl``, read-only parent, etc.) the lock degrades to a no-op
+    and the caller proceeds unlocked — matches the pre-existing
+    best-effort policy of this module.
+
+    Args:
+        path (Path): The log file path; the lock file is a sibling at
+            ``<path>.lock``.
+
+    Yields:
+        None.
+    """
+    if _fcntl is None:
+        yield
+        return
+    lock_path = path.with_name(path.name + ".lock")
+    fh: IO[bytes] | None = None
+    try:
+        fh = lock_path.open("ab")
+    except OSError as exc:
+        _LOGGER.debug("hook_log: lock open %s failed: %s", lock_path, exc)
+        yield
+        return
+    try:
+        _fcntl.flock(fh.fileno(), _fcntl.LOCK_EX)
+    except OSError as exc:
+        _LOGGER.debug("hook_log: flock acquire failed: %s", exc)
+        fh.close()
+        yield
+        return
+    try:
+        yield
+    finally:
+        with contextlib.suppress(OSError):
+            _fcntl.flock(fh.fileno(), _fcntl.LOCK_UN)
+        with contextlib.suppress(OSError):
+            fh.close()
+
+
+def _maybe_rotate(path: Path) -> None:
+    """Cap ``path`` at ``_MAX_LOG_BYTES`` by dropping the oldest half in place.
+
+    The fast path is a single ``stat`` syscall — when the file is under
+    the cap (the overwhelmingly common case on every fire) we do nothing.
+    When over the cap we read the file, find the first newline at-or-after
+    the midpoint byte, and atomically replace the original with the bytes
+    *after* that newline. Splitting on a newline boundary preserves the
+    JSON Lines invariant: every retained line is a complete record.
+
+    We picked this over ``logging.handlers.RotatingFileHandler`` because:
+
+    1. ``hook_log`` deliberately avoids the ``logging`` framework — see
+       module docstring. Adding a handler reintroduces the configuration
+       fragility we were dodging.
+    2. ``RotatingFileHandler`` produces ``hook.log.1``, ``hook.log.2`` …
+       sidecar files; our forensic story is "one file, tail it". Users
+       have already wired up tooling around that path.
+    3. In-place truncate-to-second-half is O(n) on the rare rotation
+       event and zero-cost on every other write. Backup file management
+       would add steady-state inode pressure for no benefit.
+
+    Args:
+        path (Path): The log file to inspect. Need not exist — the
+            ``FileNotFoundError`` branch of the ``stat`` call returns
+            cleanly via the ``OSError`` guard.
+
+    Returns:
+        None
+    """
+    try:
+        size = path.stat().st_size
+    except OSError as exc:
+        _LOGGER.debug("hook_log: stat for rotation failed: %s", exc)
+        return
+
+    if size < _MAX_LOG_BYTES:
+        return
+
+    try:
+        data = path.read_bytes()
+    except OSError as exc:
+        _LOGGER.debug("hook_log: read for rotation failed: %s", exc)
+        return
+
+    midpoint = len(data) // 2
+    cut = data.find(b"\n", midpoint)
+    # ``find`` returns -1 when the second half has no newline at all,
+    # meaning the file is one giant record with no framing left to
+    # preserve. Drop the lot rather than split a record mid-byte.
+    tail = b"" if cut == -1 else data[cut + 1 :]
+
+    # Atomic replace: write to a sibling temp file then rename. This
+    # avoids the truncation window where a concurrent reader would see
+    # an empty file, and matches the contract that ``hook.log`` always
+    # contains complete JSONL framing.
+    tmp_path = path.with_name(path.name + ".rot")
+    try:
+        tmp_path.write_bytes(tail)
+        tmp_path.replace(path)
+    except OSError as exc:
+        _LOGGER.debug("hook_log: rotation rename failed: %s", exc)
+        # Best-effort cleanup of the temp file; ignore failures.
+        with contextlib.suppress(OSError):
+            tmp_path.unlink(missing_ok=True)

package/plugin/src/claude_smart/internal_call.py

@@ -32,6 +32,8 @@ Detection signals, OR'd:
   - Known Codex-internal prompt templates (title generation and home-screen
     suggestions). These are model calls made by Codex itself, not user
     coding turns, and must never be reflected into claude-smart memory.
+  - Known orphan Codex-internal response bodies, for cases where the Stop
+    payload contains only the generated metadata and not the internal prompt.
 """
 
 from __future__ import annotations
@@ -140,3 +142,31 @@ def is_codex_title_response(content: Any) -> bool:
         and isinstance(parsed.get("title"), str)
         and bool(parsed["title"].strip())
     )
+
+
+def is_codex_suggestions_response(content: Any) -> bool:
+    """True for Codex's home-screen suggestion-generator response body.
+
+    Codex can run a separate suggestion task whose Stop payload contains
+    generated JSON like ``{"suggestions": [...]}`` with no corresponding user
+    turn. Those suggestions are UI metadata, not a user interaction.
+    """
+    if not isinstance(content, str):
+        return False
+    try:
+        parsed = json.loads(content)
+    except json.JSONDecodeError:
+        return False
+    if not isinstance(parsed, dict) or set(parsed) != {"suggestions"}:
+        return False
+    suggestions = parsed.get("suggestions")
+    if not isinstance(suggestions, list):
+        return False
+    for item in suggestions:
+        if not isinstance(item, dict):
+            return False
+        if set(item) != {"title", "description", "prompt", "appId"}:
+            return False
+        if not all(isinstance(item.get(key), str) for key in item):
+            return False
+    return True

package/plugin/src/claude_smart/publish.py

@@ -22,6 +22,7 @@ def publish_unpublished(
     project_id: str,
     force_extraction: bool,
     skip_aggregation: bool,
+    override_learning_stall: bool = False,
     adapter: Adapter | None = None,
 ) -> tuple[PublishStatus, int]:
     """Drain the session buffer to reflexio and stamp the high-water mark.
@@ -35,6 +36,9 @@ def publish_unpublished(
             globally per agent rather than per project.
         force_extraction (bool): Whether to ask reflexio to run extraction
             synchronously instead of queuing for the next sweep.
+        override_learning_stall (bool): Whether to bypass a recorded
+            provider auth/billing stall. Automatic hooks must leave this
+            False; explicit manual retries set it True.
         skip_aggregation (bool): When True, reflexio extracts preferences and
             raw project-specific skill entries but skips the rollup into
             shared skills. claude-smart passes False on every publish
@@ -63,6 +67,7 @@ def publish_unpublished(
         project_id=project_id,
         interactions=interactions,
         force_extraction=force_extraction,
+        override_learning_stall=override_learning_stall,
         skip_aggregation=skip_aggregation,
     )
     if ok:

package/plugin/src/claude_smart/reflexio_adapter.py

@@ -8,16 +8,26 @@ from __future__ import annotations
 
 import logging
 import os
+import inspect
+from collections.abc import Sequence
 from concurrent.futures import ThreadPoolExecutor
-from dataclasses import dataclass
-from typing import Any, Sequence
+from dataclasses import dataclass, field
+from typing import Any
 
+from claude_smart import env_config
 from claude_smart import runtime
 
 _LOGGER = logging.getLogger(__name__)
 
 _ENV_URL = "REFLEXIO_URL"
+_ENV_API_KEY = "REFLEXIO_API_KEY"
 _DEFAULT_URL = "http://localhost:8071/"
+# Cap every HTTP round-trip from a hook so a hung backend can't stall the
+# Claude Code / Codex session. reflexio's client default is 300s, which is
+# fine for batch workloads but unacceptable on the hook path — a single
+# unhealthy POST would freeze the user's prompt. 5s matches the precedent
+# in ``ids.py`` for short-lived hook HTTP calls.
+_HTTP_TIMEOUT_SECONDS = 5
 _SEARCH_MODE_HYBRID = "hybrid"  # reflexio.models.config_schema.SearchMode.HYBRID
 _UNIFIED_ENTITY_TYPES = ("profiles", "user_playbooks", "agent_playbooks")
 _AGENT_PLAYBOOK_APPROVAL_STATUSES = ("pending", "approved")
@@ -34,9 +44,13 @@ class Adapter:
     """
 
     url: str = ""
+    api_key: str = ""
+    read_errors: list[str] = field(default_factory=list, init=False)
 
     def __post_init__(self) -> None:
+        env_config.load_reflexio_env()
         self.url = self.url or os.environ.get(_ENV_URL, _DEFAULT_URL)
+        self.api_key = self.api_key or os.environ.get(_ENV_API_KEY, "")
         self._client: Any | None = None
 
     # -----------------------------------------------------------------
@@ -53,7 +67,18 @@ class Adapter:
             _LOGGER.debug("reflexio not importable: %s", exc)
             return None
         try:
-            self._client = ReflexioClient(url_endpoint=self.url)
+            try:
+                self._client = ReflexioClient(
+                    url_endpoint=self.url,
+                    api_key=self.api_key,
+                    timeout=_HTTP_TIMEOUT_SECONDS,
+                )
+            except TypeError:
+                # Pre-0.2.x reflexio releases didn't accept ``timeout``;
+                # fall back so hooks still work against older pinned clients.
+                self._client = ReflexioClient(
+                    url_endpoint=self.url, api_key=self.api_key
+                )
         except Exception as exc:  # noqa: BLE001 — adapter must never raise.
             _LOGGER.warning("Failed to construct ReflexioClient: %s", exc)
             return None
@@ -70,6 +95,7 @@ class Adapter:
         project_id: str,
         interactions: Sequence[dict[str, Any]],
         force_extraction: bool = False,
+        override_learning_stall: bool = False,
         skip_aggregation: bool = False,
     ) -> bool:
         """Publish buffered interactions to reflexio. Returns True on success."""
@@ -79,15 +105,22 @@ class Adapter:
         if client is None:
             return False
         try:
-            client.publish_interaction(
-                user_id=project_id,
-                interactions=list(interactions),
-                agent_version=runtime.agent_version(),
-                session_id=session_id,
-                wait_for_response=False,
-                force_extraction=force_extraction,
-                skip_aggregation=skip_aggregation,
-            )
+            kwargs = {
+                "user_id": project_id,
+                "interactions": list(interactions),
+                "agent_version": runtime.agent_version(),
+                "session_id": session_id,
+                "wait_for_response": False,
+                "force_extraction": force_extraction,
+                "skip_aggregation": skip_aggregation,
+            }
+            if _supports_keyword(client.publish_interaction, "override_learning_stall"):
+                kwargs["override_learning_stall"] = override_learning_stall
+            elif override_learning_stall:
+                _LOGGER.debug(
+                    "publish_interaction client does not support override_learning_stall"
+                )
+            client.publish_interaction(**kwargs)
             return True
         except Exception as exc:  # noqa: BLE001
             _LOGGER.warning("publish_interaction failed: %s", exc)
@@ -232,13 +265,20 @@ class Adapter:
         if client is None:
             return []
         try:
-            response = client.search_user_playbooks(
-                user_id=project_id,
-                status_filter=[None],  # None => CURRENT in reflexio's filter API
-                top_k=top_k,
-            )
+            if hasattr(client, "get_user_playbooks"):
+                response = client.get_user_playbooks(
+                    user_id=project_id,
+                    status_filter=[None],  # None => CURRENT in reflexio's filter API
+                    limit=top_k,
+                )
+            else:
+                response = client.search_user_playbooks(
+                    user_id=project_id,
+                    status_filter=[None],
+                    top_k=top_k,
+                )
         except Exception as exc:  # noqa: BLE001
-            _LOGGER.debug("search_user_playbooks failed: %s", exc)
+            self._record_read_error("fetch_user_playbooks", exc)
             return []
         return _extract_items(response, "user_playbooks")
 
@@ -260,13 +300,20 @@ class Adapter:
         if client is None:
             return []
         try:
-            response = client.search_agent_playbooks(
-                agent_version=runtime.agent_version(),
-                status_filter=[None],
-                top_k=top_k,
-            )
+            if hasattr(client, "get_agent_playbooks"):
+                response = client.get_agent_playbooks(
+                    agent_version=runtime.agent_version(),
+                    status_filter=[None],
+                    limit=top_k,
+                )
+            else:
+                response = client.search_agent_playbooks(
+                    agent_version=runtime.agent_version(),
+                    status_filter=[None],
+                    top_k=top_k,
+                )
         except Exception as exc:  # noqa: BLE001
-            _LOGGER.debug("search_agent_playbooks failed: %s", exc)
+            self._record_read_error("fetch_agent_playbooks", exc)
             return []
         return _filter_rejected_agent_playbooks(
             _extract_items(response, "agent_playbooks")
@@ -278,13 +325,20 @@ class Adapter:
         if client is None:
             return []
         try:
+            if hasattr(client, "get_all_profiles"):
+                response = client.get_all_profiles(limit=max(top_k * 20, 100))
+                return [
+                    item
+                    for item in _extract_items(response, "user_profiles")
+                    if _field(item, "user_id") == project_id
+                ][:top_k]
             response = client.search_user_profiles(
                 user_id=project_id,
                 query="",
                 top_k=top_k,
             )
         except Exception as exc:  # noqa: BLE001
-            _LOGGER.debug("search_user_profiles failed: %s", exc)
+            self._record_read_error("fetch_project_profiles", exc)
             return []
         return _extract_items(response, "user_profiles")
 
@@ -329,7 +383,7 @@ class Adapter:
                 search_mode=_SEARCH_MODE_HYBRID,
             )
         except Exception as exc:  # noqa: BLE001
-            _LOGGER.debug("unified search failed: %s", exc)
+            self._record_read_error("unified search", exc)
             return [], [], []
         return (
             _extract_items(response, "user_playbooks"),
@@ -374,6 +428,11 @@ class Adapter:
             )
         return up_future.result(), ap_future.result(), pr_future.result()
 
+    def _record_read_error(self, operation: str, exc: Exception) -> None:
+        message = f"{operation}: {exc}"
+        self.read_errors.append(message)
+        _LOGGER.debug("%s failed: %s", operation, exc)
+
 
 def _extract_items(response: Any, field: str) -> list[Any]:
     """Pull a list field from a reflexio response object or dict, tolerating shape drift."""
@@ -386,6 +445,23 @@ def _extract_items(response: Any, field: str) -> list[Any]:
     return list(value) if value else []
 
 
+def _field(item: Any, field: str) -> Any:
+    if isinstance(item, dict):
+        return item.get(field)
+    return getattr(item, field, None)
+
+
+def _supports_keyword(callable_obj: Any, keyword: str) -> bool:
+    try:
+        signature = inspect.signature(callable_obj)
+    except (TypeError, ValueError):
+        return False
+    for parameter in signature.parameters.values():
+        if parameter.kind == inspect.Parameter.VAR_KEYWORD:
+            return True
+    return keyword in signature.parameters
+
+
 def _filter_rejected_agent_playbooks(items: list[Any]) -> list[Any]:
     """Drop rejected shared skills defensively, even if an older backend ignores filters."""
     return [

package/plugin/uv.lock

@@ -419,7 +419,7 @@ wheels = [
 
 [[package]]
 name = "claude-smart"
-version = "0.2.30"
+version = "0.2.32"
 source = { editable = "." }
 dependencies = [
     { name = "chromadb" },