claude-smart 0.2.31 → 0.2.32

package/plugin/src/claude_smart/cli.py

@@ -33,10 +33,11 @@ import time
 from dataclasses import dataclass
 from pathlib import Path
 
-from claude_smart import context_format, ids, publish, state
+from claude_smart import context_format, env_config, ids, publish, state
 from claude_smart.reflexio_adapter import Adapter
 
-_REFLEXIO_ENV_PATH = Path.home() / ".reflexio" / ".env"
+_REFLEXIO_ENV_PATH = env_config.REFLEXIO_ENV_PATH
+_MANAGED_REFLEXIO_URL = env_config.MANAGED_REFLEXIO_URL
 _DEFAULT_MARKETPLACE_SOURCE = "ReflexioAI/claude-smart"
 _PLUGIN_SPEC = "claude-smart@reflexioai"
 _CODEX_MARKETPLACE_NAME = "reflexioai"
@@ -70,6 +71,16 @@ _BACKEND_SCRIPT = _SCRIPTS_DIR / "backend-service.sh"
 _DASHBOARD_SCRIPT = _SCRIPTS_DIR / "dashboard-service.sh"
 _REFLEXIO_DIR = Path.home() / ".reflexio"
 _STATE_DIR = Path.home() / ".claude-smart"
+_LOCAL_DATA_NOTICE = (
+    "Local data was kept so reinstalling claude-smart can reuse your learned "
+    "rules, sessions, logs, and local Reflexio data.\n"
+    "Kept folders:\n"
+    "  ~/.claude-smart\n"
+    "  ~/.reflexio\n"
+    "Delete them only if you want a full reset or need to remove local "
+    "claude-smart data from this machine:\n"
+    "  rm -rf ~/.claude-smart ~/.reflexio\n"
+)
 _INSTALL_FAILURE_MARKER = _STATE_DIR / "install-failed"
 _DEFAULT_STORAGE_ROOT = _REFLEXIO_DIR / "data"
 _REFLEXIO_CONFIG_PATH = _REFLEXIO_DIR / "configs" / "config_self-host-org.json"
@@ -127,9 +138,21 @@ def _seed_reflexio_env() -> list[str]:
     prefix = "" if not existing or existing.endswith("\n") else "\n"
     with _REFLEXIO_ENV_PATH.open("a") as fh:
         fh.write(prefix + "\n".join(f"{f}=1" for f in missing) + "\n")
+    _REFLEXIO_ENV_PATH.chmod(0o600)
     return missing
 
 
+def _seed_managed_reflexio_env(*, api_key: str, reflexio_url: str) -> list[str]:
+    """Write managed Reflexio connection settings to ``~/.reflexio/.env``."""
+    return env_config.set_env_vars(
+        _REFLEXIO_ENV_PATH,
+        {
+            env_config.REFLEXIO_URL_ENV: reflexio_url,
+            env_config.REFLEXIO_API_KEY_ENV: api_key,
+        },
+    )
+
+
 def _find_claude_code_plugin_root() -> Path | None:
     """Locate the installed Claude Code plugin root after native install."""
     cache_root = (
@@ -162,10 +185,9 @@ def _find_claude_code_plugin_root() -> Path | None:
         ]
     )
     for candidate in candidates:
-        if (
-            (candidate / "pyproject.toml").is_file()
-            and (candidate / "scripts" / "smart-install.sh").is_file()
-        ):
+        if (candidate / "pyproject.toml").is_file() and (
+            candidate / "scripts" / "smart-install.sh"
+        ).is_file():
             return candidate
     return None
 
@@ -735,7 +757,26 @@ def _register_codex_marketplace(root: Path) -> tuple[bool, str]:
     return False, output or "Codex CLI does not expose plugin marketplace commands"
 
 
-def cmd_install_codex(_args: argparse.Namespace) -> int:
+def _configure_reflexio_setup(args: argparse.Namespace) -> None:
+    api_key = (getattr(args, "api_key", "") or "").strip()
+    if api_key:
+        reflexio_url = (
+            getattr(args, "reflexio_url", "") or _MANAGED_REFLEXIO_URL
+        ).strip()
+        added = _seed_managed_reflexio_env(api_key=api_key, reflexio_url=reflexio_url)
+        changed = ", ".join(added) if added else "managed Reflexio settings"
+        sys.stdout.write(
+            f"Configured {_REFLEXIO_ENV_PATH} for managed Reflexio "
+            f"({changed}; API key {env_config.mask_secret(api_key)}).\n"
+        )
+        return
+
+    added = _seed_reflexio_env()
+    if added:
+        sys.stdout.write(f"Seeded {_REFLEXIO_ENV_PATH} with {', '.join(added)}.\n")
+
+
+def cmd_install_codex(args: argparse.Namespace) -> int:
     """Install the claude-smart plugin marketplace for Codex.
 
     Only supported from a source checkout — the wheel ships the Python
@@ -767,9 +808,7 @@ def cmd_install_codex(_args: argparse.Namespace) -> int:
         return 1
     marketplace_root = _prepare_codex_local_marketplace()
 
-    added = _seed_reflexio_env()
-    if added:
-        sys.stdout.write(f"Seeded {_REFLEXIO_ENV_PATH} with {', '.join(added)}.\n")
+    _configure_reflexio_setup(args)
 
     hooks_ok, hooks_msg = _enable_codex_plugin_hooks()
     if hooks_ok:
@@ -871,9 +910,7 @@ def cmd_install(args: argparse.Namespace) -> int:
             sys.stderr.write(f"error: {' '.join(cmd)} failed (exit {exc.returncode})\n")
             return exc.returncode or 1
 
-    added = _seed_reflexio_env()
-    if added:
-        sys.stdout.write(f"Seeded {_REFLEXIO_ENV_PATH} with {', '.join(added)}.\n")
+    _configure_reflexio_setup(args)
 
     bootstrapped, message = _bootstrap_claude_code_install()
     if not bootstrapped:
@@ -953,8 +990,7 @@ def cmd_uninstall(_args: argparse.Namespace) -> int:
 
     sys.stdout.write(
         "\nclaude-smart uninstalled. Restart Claude Code to apply.\n"
-        "Local data in ~/.reflexio/ and ~/.claude-smart/ was left in place — "
-        "remove manually if desired.\n"
+        f"{_LOCAL_DATA_NOTICE}"
     )
     return 0
 
@@ -991,8 +1027,8 @@ def cmd_uninstall_codex(_args: argparse.Namespace) -> int:
         sys.stderr.write(f"warning: could not update {_CODEX_CONFIG_PATH}\n")
     sys.stdout.write(
         "claude-smart Codex plugin and marketplace state removed. Restart Codex to apply. "
-        "Codex's global hook feature flags and local data under ~/.reflexio "
-        "and ~/.claude-smart were left in place.\n"
+        "Codex's global hook feature flags were left in place.\n"
+        f"{_LOCAL_DATA_NOTICE}"
     )
     return 0
 
@@ -1026,6 +1062,13 @@ def cmd_show(args: argparse.Namespace) -> int:
         agent_playbooks=agent_playbooks,
         profiles=profiles,
     )
+    if not md and adapter.read_errors:
+        sys.stdout.write(
+            "Could not read skills or preferences from Reflexio for "
+            f"project `{project_id}` at `{adapter.url}`.\n"
+            f"First error: {adapter.read_errors[0]}\n"
+        )
+        return 1
     sys.stdout.write(
         md or f"_No skills or preferences yet for project `{project_id}`._\n"
     )
@@ -1035,8 +1078,10 @@ def cmd_show(args: argparse.Namespace) -> int:
 def cmd_learn(args: argparse.Namespace) -> int:
     """Force reflexio extraction over the active session's interactions.
 
-    Publishes unpublished interactions with ``force_extraction=True`` so
-    extraction runs immediately rather than at the next batch interval.
+    Publishes unpublished interactions with ``force_extraction=True`` and
+    ``override_learning_stall=True`` as an explicit retry request rather than
+    waiting for the next batch interval. The publish call itself remains
+    non-blocking: ``Adapter.publish`` sends ``wait_for_response=False``.
     When ``args.note`` is provided, the note is appended to the session
     buffer as a neutral User turn before publishing — letting the user
     capture an explicit insight, preference, or workflow note alongside
@@ -1074,6 +1119,7 @@ def cmd_learn(args: argparse.Namespace) -> int:
         session_id=session_id,
         project_id=project_id,
         force_extraction=True,
+        override_learning_stall=True,
         skip_aggregation=False,
     )
     if status == "ok":
@@ -1573,9 +1619,15 @@ def _resolve_reflexio_url() -> str:
         str: The ``REFLEXIO_URL`` env var if set, otherwise the default
             local backend endpoint.
     """
+    env_config.load_reflexio_env()
     return os.environ.get("REFLEXIO_URL", "http://localhost:8071/")
 
 
+def _resolve_reflexio_api_key() -> str:
+    env_config.load_reflexio_env()
+    return os.environ.get("REFLEXIO_API_KEY", "")
+
+
 def _format_deleted_counts(deleted_counts: object) -> str:
     """Render ``deleted_counts`` from a ``clear_user_data`` response as a summary.
 
@@ -1644,7 +1696,10 @@ def cmd_clear_user(args: argparse.Namespace) -> int:
         return 1
 
     try:
-        client = ReflexioClient(url_endpoint=_resolve_reflexio_url())
+        client = ReflexioClient(
+            url_endpoint=_resolve_reflexio_url(),
+            api_key=_resolve_reflexio_api_key(),
+        )
         # The companion reflexio PR adds ``clear_user_data``; keep the
         # CLI buildable until both sides ship together.
         response = client.clear_user_data(user_id)  # pyright: ignore[reportAttributeAccessIssue]
@@ -1676,6 +1731,16 @@ def _build_parser() -> argparse.ArgumentParser:
         default=_DEFAULT_MARKETPLACE_SOURCE,
         help="Marketplace ref — GitHub owner/repo, or a local directory path",
     )
+    inst.add_argument(
+        "--api-key",
+        default="",
+        help="Configure managed Reflexio with this API key instead of local mode",
+    )
+    inst.add_argument(
+        "--reflexio-url",
+        default=_MANAGED_REFLEXIO_URL,
+        help="Managed Reflexio URL used only when --api-key is provided",
+    )
     inst.set_defaults(func=cmd_install)
 
     upd = sub.add_parser("update", help="Update claude-smart to the latest version")
@@ -1767,6 +1832,7 @@ def _build_parser() -> argparse.ArgumentParser:
 
 
 def main(argv: list[str] | None = None) -> int:
+    env_config.load_reflexio_env()
     parser = _build_parser()
     args = parser.parse_args(argv)
     return args.func(args)

package/plugin/src/claude_smart/context_format.py

@@ -2,9 +2,18 @@
 
 from __future__ import annotations
 
-from typing import Any, Iterable
+import os
+from collections.abc import Iterable
+from typing import Any
+from urllib.parse import quote, urlparse
 
-from claude_smart import cs_cite
+from claude_smart import cs_cite, env_config
+
+_DASHBOARD_URL_ENV = "CLAUDE_SMART_DASHBOARD_URL"
+_CITATION_LINK_STYLE_ENV = "CLAUDE_SMART_CITATION_LINK_STYLE"
+_DEFAULT_DASHBOARD_URL = "http://localhost:3001"
+_REFLEXIO_URL_ENV = "REFLEXIO_URL"
+_LOCAL_REFLEXIO_HOSTS = {"localhost", "127.0.0.1", "0.0.0.0", "::1"}
 
 
 def _first_nonempty(*values: Any) -> str:
@@ -93,7 +102,17 @@ def render_with_registry(
     if profile_lines:
         sections.append("### Project preferences")
         sections.extend(profile_lines)
-    sections.append(cs_cite.CITATION_INSTRUCTION)
+    instruction = _citation_instruction(
+        os.environ.get("CLAUDE_SMART_CITATIONS", "on"),
+        os.environ.get(_CITATION_LINK_STYLE_ENV, "markdown"),
+    )
+    if instruction:
+        sections.append(instruction)
+    exact_osc8_marker = _exact_osc8_marker_instruction(
+        playbook_entries + profile_entries
+    )
+    if exact_osc8_marker:
+        sections.append(exact_osc8_marker)
     return "\n".join(sections) + "\n", playbook_entries + profile_entries
 
 
@@ -164,16 +183,159 @@ def render_inline_with_registry(
     if profile_lines:
         sections.append("### Relevant project preferences")
         sections.extend(profile_lines)
-    sections.append(cs_cite.CITATION_INSTRUCTION)
+    instruction = _citation_instruction(
+        os.environ.get("CLAUDE_SMART_CITATIONS", "on"),
+        os.environ.get(_CITATION_LINK_STYLE_ENV, "markdown"),
+    )
+    if instruction:
+        sections.append(instruction)
+    exact_osc8_marker = _exact_osc8_marker_instruction(
+        playbook_entries + profile_entries
+    )
+    if exact_osc8_marker:
+        sections.append(exact_osc8_marker)
     return "\n".join(sections) + "\n", playbook_entries + profile_entries
 
 
+def render_inline_compact_with_registry(
+    *,
+    project_id: str,
+    user_playbooks: Iterable[Any],
+    agent_playbooks: Iterable[Any],
+    profiles: Iterable[Any],
+) -> tuple[str, list[dict[str, Any]]]:
+    """Render mid-session context as one compact logical line.
+
+    Codex currently displays ``UserPromptSubmit.additionalContext`` in the TUI.
+    This renderer preserves the model-visible ids and rule URLs needed for
+    citation tracking while avoiding the multi-line markdown block used by
+    hosts that can hide hook context.
+    """
+    del project_id  # kept for symmetry with ``render_inline_with_registry``.
+    _, playbook_entries = _format_combined_playbooks(
+        agent_playbooks=agent_playbooks, user_playbooks=user_playbooks
+    )
+    _, profile_entries = _format_profiles(profiles)
+    entries = playbook_entries + profile_entries
+    if not entries:
+        return "", []
+
+    skill_parts = []
+    preference_parts = []
+    marker_parts = []
+    link_style = os.environ.get(_CITATION_LINK_STYLE_ENV, "markdown")
+    for entry in entries:
+        title = _one_line(str(entry.get("title") or entry["content"]))
+        content = _one_line(str(entry["content"]))
+        rule_url = str(entry.get("rule_url") or "")
+        if link_style == "osc8" and rule_url:
+            linked_title = _osc8_link(
+                rule_url, _strip_trailing_sentence_punctuation(title)
+            )
+            item = _osc8_link(rule_url, _strip_trailing_sentence_punctuation(content))
+            marker_parts.append(linked_title)
+        else:
+            item = f"{content} (title: {title}"
+            if rule_url:
+                item += f"; open: {rule_url}"
+            item += ")"
+        if entry.get("kind") == "profile":
+            preference_parts.append(item)
+        else:
+            skill_parts.append(item)
+
+    memory_sections = []
+    if skill_parts:
+        label = "Skill" if len(skill_parts) == 1 else "Skills"
+        memory_sections.append(f"{label}: {'; '.join(skill_parts)}")
+    if preference_parts:
+        label = "Preference" if len(preference_parts) == 1 else "Preferences"
+        memory_sections.append(f"{label}: {'; '.join(preference_parts)}")
+    sections = [f"claude-smart: using relevant memory. {'. '.join(memory_sections)}."]
+    instruction = _compact_citation_instruction(marker_parts)
+    if instruction:
+        sections.append(instruction)
+    return " ".join(sections) + "\n", entries
+
+
+def _compact_citation_instruction(marker_parts: list[str] | None = None) -> str:
+    if os.environ.get("CLAUDE_SMART_CITATIONS", "on") == "off":
+        return ""
+    link_style = os.environ.get(_CITATION_LINK_STYLE_ENV, "markdown")
+    if link_style == "osc8" and marker_parts:
+        marker = f"✨ claude-smart rule applied: {' | '.join(marker_parts)}"
+        separator_instruction = (
+            " Separate multiple linked memories with the visible ` | ` separator."
+            if len(marker_parts) > 1
+            else ""
+        )
+        return _remoteize_citation_instruction(
+            f"If used, copy this final marker exactly, preserving its hidden "
+            f"OSC 8 terminal link: `{marker}`.{separator_instruction} "
+            f"Skip when unrelated."
+        )
+    if link_style == "osc8":
+        return _remoteize_citation_instruction(
+            "If used, end with `✨ claude-smart rule applied:` followed by "
+            "the same linked memory text; keep the link, but do not show the "
+            "URL. Skip when unrelated."
+        )
+    return _remoteize_citation_instruction(
+        "Only if a listed [cs:...] item materially changes your answer, end "
+        "with one final marker like `✨ claude-smart rule applied: "
+        "[verify process state](http://localhost:3001/rules/s1-123)` using "
+        "the shown rule URL; skip the marker when unrelated."
+    )
+
+
+def _citation_instruction(mode: str, link_style: str) -> str:
+    return _remoteize_citation_instruction(
+        cs_cite.citation_instruction(mode, link_style)
+    )
+
+
+def _remoteize_citation_instruction(text: str) -> str:
+    playbooks_url = _remote_reflexio_page_url("playbook")
+    profiles_url = _remote_reflexio_page_url("profile")
+    if not text or not playbooks_url or not profiles_url:
+        return text
+    return text.replace("http://localhost:3001/rules/s1-123", playbooks_url).replace(
+        "http://localhost:3001/rules/p1-pref", profiles_url
+    )
+
+
+def _exact_osc8_marker_instruction(entries: list[dict[str, Any]]) -> str:
+    if os.environ.get("CLAUDE_SMART_CITATIONS", "on") == "off":
+        return ""
+    if os.environ.get(_CITATION_LINK_STYLE_ENV, "markdown") != "osc8":
+        return ""
+
+    marker_parts = []
+    for entry in entries:
+        rule_url = str(entry.get("rule_url") or "")
+        if not rule_url:
+            continue
+        title = _one_line(str(entry.get("title") or entry["content"]))
+        marker_parts.append(
+            _osc8_link(rule_url, _strip_trailing_sentence_punctuation(title))
+        )
+    if not marker_parts:
+        return ""
+
+    marker = f"✨ claude-smart rule applied: {' | '.join(marker_parts)}"
+    return (
+        "If any listed memory above was used, copy this exact final marker, "
+        f"preserving its hidden OSC 8 terminal links: `{marker}`. "
+        "Do not rename, summarize, or regroup the linked titles."
+    )
+
+
 def _format_combined_playbooks(
     *,
     agent_playbooks: Iterable[Any],
     user_playbooks: Iterable[Any],
 ) -> tuple[list[str], list[dict[str, Any]]]:
-    """Render agent playbooks first, then user playbooks, with one shared rank counter."""
+    """Render agent then user playbooks with one shared rank counter."""
     lines: list[str] = []
     entries: list[dict[str, Any]] = []
     rank = 0
@@ -205,11 +367,15 @@ def _append_playbook_bullet(
     real_id = _field(pb, id_field)
     item_id = cs_cite.rank_id("playbook", rank, real_id)
     title = _title_from_content(content)
+    dashboard_url = _dashboard_url("playbook", real_id, source_kind)
+    rule_url = _rule_url(item_id, "playbook")
     bullet = f"- [cs:{item_id}] {content}"
     if trigger:
         bullet += f" _(when: {trigger})_"
     if rationale:
         bullet += f" — *why:* {rationale}"
+    if rule_url:
+        bullet += f" _(open: {rule_url})_"
     lines.append(bullet)
     entries.append(
         {
@@ -219,6 +385,8 @@ def _append_playbook_bullet(
             "content": content,
             "real_id": str(real_id) if real_id is not None else None,
             "source_kind": source_kind,
+            "dashboard_url": dashboard_url,
+            "rule_url": rule_url,
         }
     )
     return rank
@@ -238,7 +406,12 @@ def _format_profiles(
         real_id = _field(p, "profile_id")
         item_id = cs_cite.rank_id("profile", rank, real_id)
         title = _title_from_content(content)
-        lines.append(f"- [cs:{item_id}] {content}")
+        dashboard_url = _dashboard_url("profile", real_id)
+        rule_url = _rule_url(item_id, "profile")
+        bullet = f"- [cs:{item_id}] {content}"
+        if rule_url:
+            bullet += f" _(open: {rule_url})_"
+        lines.append(bullet)
         entries.append(
             {
                 "id": item_id,
@@ -246,11 +419,64 @@ def _format_profiles(
                 "title": title,
                 "content": content,
                 "real_id": str(real_id) if real_id is not None else None,
+                "dashboard_url": dashboard_url,
+                "rule_url": rule_url,
             }
         )
     return lines, entries
 
 
+def _dashboard_url(kind: str, real_id: Any, source_kind: str | None = None) -> str:
+    remote_url = _remote_reflexio_page_url(kind)
+    if remote_url:
+        return remote_url
+    if real_id is None:
+        return ""
+    encoded_id = quote(str(real_id), safe="")
+    base = os.environ.get(_DASHBOARD_URL_ENV, _DEFAULT_DASHBOARD_URL).rstrip("/")
+    if kind == "profile":
+        return f"{base}/preferences/project/{encoded_id}"
+    if kind == "playbook":
+        skill_kind = "shared" if source_kind == "agent_playbook" else "project"
+        return f"{base}/skills/{skill_kind}/{encoded_id}"
+    return ""
+
+
+def _rule_url(item_id: str, kind: str) -> str:
+    remote_url = _remote_reflexio_page_url(kind)
+    if remote_url:
+        return remote_url
+    if not item_id:
+        return ""
+    encoded_id = quote(item_id, safe="")
+    base = os.environ.get(_DASHBOARD_URL_ENV, _DEFAULT_DASHBOARD_URL).rstrip("/")
+    return f"{base}/rules/{encoded_id}"
+
+
+def _remote_reflexio_page_url(kind: str) -> str:
+    origin = _remote_reflexio_origin()
+    if not origin:
+        return ""
+    if kind == "profile":
+        return f"{origin}/profiles"
+    if kind == "playbook":
+        return f"{origin}/playbooks"
+    return ""
+
+
+def _remote_reflexio_origin() -> str:
+    env_config.load_reflexio_env()
+    raw = os.environ.get(_REFLEXIO_URL_ENV, "").strip()
+    if not raw:
+        return ""
+    parsed = urlparse(raw)
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+        return ""
+    if (parsed.hostname or "").lower() in _LOCAL_REFLEXIO_HOSTS:
+        return ""
+    return f"{parsed.scheme}://{parsed.netloc}".rstrip("/")
+
+
 def _title_from_content(content: str, limit: int = 80) -> str:
     """Derive a compact human-readable title from a bullet's content.
 
@@ -270,6 +496,18 @@ def _title_from_content(content: str, limit: int = 80) -> str:
     return text[: limit - 1].rstrip() + "…"
 
 
+def _one_line(text: str) -> str:
+    return " ".join(text.split())
+
+
+def _osc8_link(url: str, label: str) -> str:
+    return f"\x1b]8;;{url}\x1b\\{label}\x1b]8;;\x1b\\"
+
+
+def _strip_trailing_sentence_punctuation(text: str) -> str:
+    return text.rstrip().rstrip(".!?")
+
+
 def _field(obj: Any, name: str) -> Any:
     """Read ``name`` from either an attribute or a dict key."""
     if isinstance(obj, dict):

package/plugin/src/claude_smart/context_inject.py

@@ -17,6 +17,7 @@ turn) — see the two call sites for the small policy differences.
 from __future__ import annotations
 
 import json
+import os
 import sys
 import time
 
@@ -59,7 +60,13 @@ def emit_context(
         query=query,
         top_k=top_k,
     )
-    markdown, registry = context_format.render_inline_with_registry(
+    renderer = (
+        context_format.render_inline_compact_with_registry
+        if hook_event_name == "UserPromptSubmit"
+        and os.environ.get("CLAUDE_SMART_HOST") == "codex"
+        else context_format.render_inline_with_registry
+    )
+    markdown, registry = renderer(
         project_id=project_id,
         user_playbooks=user_playbooks,
         agent_playbooks=agent_playbooks,