claude-smart 0.2.45 → 0.2.46

package/plugin/vendor/reflexio/reflexio/integrations/openclaw/plugin/src/openclaw_smart/oc_cite.py

@@ -0,0 +1,196 @@
+"""Support helpers for openclaw-smart citation tracking.
+
+Context injected by before_prompt_build / before_tool_call tags each skill
+and preference bullet with a rank-based id fingerprinted by the underlying
+real id (``[oc:s1-1a2b]`` for the first skill whose ``user_playbook_id``
+starts with ``1a2b``, ``[oc:p2-c3d4]`` for the second preference). The
+injected instruction asks the assistant to end impactful replies with a
+marker like::
+
+    ✨ 1 openclaw-smart learning applied [oc:s1-1a2b]
+
+The agent_end hook later scans the assistant text for those markers and
+resolves the ids against a per-session registry persisted at
+``~/.openclaw-smart/sessions/<session_id>.injected.jsonl``. Legacy
+``oc-cite`` Bash tool calls are still accepted as a fallback for older
+instructions.
+
+Why rank + fingerprint: rank alone resets at every injection, so a later
+injection's ``s1`` would silently overwrite an earlier entry in the
+append-only registry — if openClaw cited ``s1`` across a turn boundary,
+the resolver would pick the wrong skill. Appending the first four
+alphanumeric chars of the real id makes the id stable across injections
+in the common case (distinct real ids → distinct fingerprints), so
+cross-injection collisions become rare.
+
+This module holds:
+
+- ``rank_id``: ``p{n}-{fp}`` / ``s{n}-{fp}`` tag for a given (kind, rank,
+  real_id) tuple. Fingerprint is omitted when no real id is available.
+  ``p`` is preference, ``s`` is skill.
+- ``CITATION_CMD_RE``: regex matching a valid legacy ``oc-cite`` command line.
+- ``ensure_installed``: idempotent copy of ``plugin/bin/oc-cite`` to
+  ``~/.openclaw-smart/bin/oc-cite`` with the executable bit set.
+- ``CITATION_INSTRUCTION``: the trailer text appended to injected context
+  so the assistant knows when and how to emit the citation marker.
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import shutil
+import stat as stat_
+from pathlib import Path
+from typing import Any
+
+_LOGGER = logging.getLogger(__name__)
+
+# plugin/src/openclaw_smart/oc_cite.py -> parents[2] is plugin/
+_THIS_DIR = Path(__file__).resolve().parent
+_PLUGIN_ROOT = _THIS_DIR.parents[2]
+_SOURCE_SCRIPT = _PLUGIN_ROOT / "bin" / "oc-cite"
+_INSTALL_DIR = Path.home() / ".openclaw-smart" / "bin"
+INSTALL_PATH = _INSTALL_DIR / "oc-cite"
+
+_FINGERPRINT_LEN = 4
+
+# Match a bare `oc-cite <ids>` invocation. Ids are rank tokens of the form
+# `p<N>` (preference) or `s<N>` (skill) with an optional `-<fp>`
+# fingerprint (1-4 alphanumeric chars), optionally `oc:`-prefixed (since
+# bullets render as `[oc:p1-ab12]` and the model often copies the tag
+# verbatim). The `(?i:...)` inline flags make the prefix, kind letter,
+# and fingerprint case-insensitive so `OC:P1-AB12` is accepted. Tokens
+# may be comma- and/or whitespace-separated. Chained commands (&&, |, ;)
+# and extra trailing tokens remain rejected by the anchored `\s*$`
+# terminator so accidental mentions don't register as citations.
+_ID_TOKEN = r"(?i:oc:)?(?i:[ps])\d+(?:-(?i:[a-z0-9]){1,4})?"  # noqa: S105 — regex pattern, not a secret.
+_ID_SEP = r"[,\s]+"
+CITATION_CMD_RE = re.compile(
+    rf"^\s*(?:[^\s]*/)?oc-cite\s+({_ID_TOKEN}(?:{_ID_SEP}{_ID_TOKEN})*)\s*$"
+)
+_CLEAN_ID_RE = re.compile(r"^(?i:oc:)?((?i:[ps])\d+(?:-(?i:[a-z0-9]){1,4})?)$")
+_SPLIT_RE = re.compile(_ID_SEP)
+_TEXT_CITATION_LINE_RE = re.compile(
+    r"(?im)^\s*✨\s+\d+\s+openclaw-smart learning(?:s)? applied\s+"
+    r"\[oc:(?P<ids>[^\]]+)\]\s*$"
+)
+
+CITATION_INSTRUCTION = (
+    "_First, fully answer the user — citation does not change what or how "
+    "you reply. Then, as a final step, consider whether to cite: if — and "
+    "only if — an injected `[oc:…]` item materially changed your reply "
+    "(different wording, action, or conclusion than you would have produced "
+    "without it), append exactly one final citation line after your answer. "
+    "Do not call `oc-cite` or any other tool for citations. Ids come verbatim "
+    "from the `[oc:…]` tags — keep the leading `p` (preference) or `s` "
+    "(skill) and the `-<fp>` suffix. Use this exact format for one id: "
+    "`✨ 1 openclaw-smart learning applied [oc:s1-ab12]`. Use this exact "
+    "format for multiple ids: `✨ 2 openclaw-smart learnings applied "
+    "[oc:s1-ab12,p2-cd34]`, where the number is the count of ids in the "
+    "brackets. Never emit a standalone wrapper like `✨s1-ab12✨` or "
+    "`✨abc123✨`; those are not openclaw-smart citations and cannot be "
+    "resolved. Default is to skip. If an item is merely on-topic, confirms "
+    "what you already planned, or your reply would read the same without it, "
+    "do not cite — end the turn normally with your reply. When unsure, skip. "
+    "Do not add any other text, tool calls, or role markers after the final "
+    "citation line._"
+)
+
+
+def _fingerprint(real_id: Any) -> str:
+    """Return the first ``_FINGERPRINT_LEN`` alphanumeric chars of ``real_id``."""
+    if real_id is None:
+        return ""
+    return "".join(c for c in str(real_id).lower() if c.isalnum())[:_FINGERPRINT_LEN]
+
+
+def rank_id(kind: str, rank: int, real_id: Any = None) -> str:
+    """Return the citation id for a skill or preference item.
+
+    Format is ``{letter}{rank}-{fingerprint}`` where ``letter`` is ``p`` for
+    preferences and ``s`` for skills, ``rank`` is the 1-based position within
+    the current retrieval batch, and ``fingerprint`` is up to 4 alphanumeric
+    chars derived from ``real_id``. The fingerprint is omitted when no real
+    id is available (falling back to the rank form ``s1`` / ``p1``).
+
+    Raises:
+        ValueError: If ``kind`` is not ``"profile"`` or ``"playbook"``.
+    """
+    if kind == "profile":
+        prefix = "p"
+    elif kind == "playbook":
+        prefix = "s"
+    else:
+        raise ValueError(f"unknown citation kind: {kind!r}")
+    fp = _fingerprint(real_id)
+    return f"{prefix}{rank}-{fp}" if fp else f"{prefix}{rank}"
+
+
+def parse_citation_command(command: str) -> list[str]:
+    """Extract citation ids from an ``oc-cite`` Bash command string.
+
+    Returns an empty list when the command does not match the expected shape
+    (chained commands, extra arguments, or anything other than a bare
+    ``oc-cite <ids>`` invocation are rejected to avoid false positives from
+    accidental mentions).
+    """
+    match = CITATION_CMD_RE.match(command or "")
+    if not match:
+        return []
+    return _parse_id_tokens(match.group(1))
+
+
+def parse_text_citations(text: str) -> list[str]:
+    """Extract text-only citation ids from a final learning marker line.
+
+    The parser intentionally only accepts lines containing the visual
+    ``openclaw-smart learning(s) applied`` marker, so ordinary references to
+    injected ``[oc:...]`` ids inside an answer do not count as citations.
+    When multiple matching lines exist, the last one wins because the
+    instruction requires the citation marker to be final.
+    """
+    matches = list(_TEXT_CITATION_LINE_RE.finditer(text or ""))
+    if not matches:
+        return []
+    return _parse_id_tokens(matches[-1].group("ids"))
+
+
+def _parse_id_tokens(raw_ids: str) -> list[str]:
+    return [
+        clean.group(1).lower()
+        for tok in _SPLIT_RE.split(raw_ids.strip())
+        if (clean := _CLEAN_ID_RE.match(tok))
+    ]
+
+
+def ensure_installed() -> Path:
+    """Idempotently install ``oc-cite`` into ``~/.openclaw-smart/bin/``.
+
+    Called from every before_tool_call / before_prompt_build inject, so we
+    short-circuit when the target file already exists with the executable
+    bit set — the steady-state path is one ``stat`` syscall instead of
+    mkdir + copy + stat + chmod. Keying on filesystem state (rather than a
+    module-level boolean) keeps test isolation working when tests
+    monkeypatch ``INSTALL_PATH`` to a fresh tmpdir.
+
+    Never raises — filesystem errors are logged at DEBUG and the caller
+    proceeds with injection regardless (the citation feature degrades to
+    silent if the script is unreachable).
+    """
+    try:
+        if (
+            INSTALL_PATH.is_file()
+            and INSTALL_PATH.stat().st_mode & stat_.S_IXUSR
+            and _SOURCE_SCRIPT.is_file()
+            and INSTALL_PATH.read_bytes() == _SOURCE_SCRIPT.read_bytes()
+        ):
+            return INSTALL_PATH
+        _INSTALL_DIR.mkdir(parents=True, exist_ok=True)
+        if _SOURCE_SCRIPT.is_file():
+            shutil.copy2(_SOURCE_SCRIPT, INSTALL_PATH)
+            mode = INSTALL_PATH.stat().st_mode
+            INSTALL_PATH.chmod(mode | stat_.S_IXUSR | stat_.S_IXGRP | stat_.S_IXOTH)
+    except OSError as exc:
+        _LOGGER.debug("oc-cite install failed: %s", exc)
+    return INSTALL_PATH

package/plugin/vendor/reflexio/reflexio/integrations/openclaw/plugin/src/openclaw_smart/optimizer_assistant.py

@@ -0,0 +1,272 @@
+"""Local-script assistant backend for Reflexio playbook optimization.
+
+Reflexio's ``LocalScriptAssistant`` sends one JSON payload on stdin and expects
+one JSON object on stdout. This module bridges that protocol to a guarded
+``openclaw infer model run`` subprocess so candidate playbooks can be evaluated
+against the local model without re-entering openclaw-smart hooks.
+
+Compared to claude-smart's variant, openClaw's ``infer model run`` is a one-shot
+completion (not a full agent with tool access), so we cannot grant read-only
+tool calls during evaluation. The optimizer therefore evaluates rules purely
+based on the prompt context. ``OPENCLAW_SMART_INTERNAL=1`` is set on the
+subprocess env to short-circuit our own hooks (recursion guard).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess  # noqa: S404 — subprocess is the integration point.
+import sys
+from pathlib import Path
+from typing import Any
+
+_CLI_TIMEOUT_SECONDS = 300
+ENV_CLI_PATH = "OPENCLAW_BIN"
+ENV_DEFAULT_MODEL = "OPENCLAW_DEFAULT_MODEL"
+ENV_TIMEOUT = "OPENCLAW_OPTIMIZER_TIMEOUT"
+
+
+class OptimizerAssistantError(Exception):
+    """Raised for any local assistant protocol or openClaw CLI failure."""
+
+
+def main() -> int:
+    """Console-script entrypoint for ``openclaw-smart-optimizer-assistant``.
+
+    Returns:
+        int: Exit code (0 on success, 1 on any error).
+    """
+    try:
+        payload = _read_payload()
+        messages = _validated_list(payload, "messages")
+        playbooks = _validated_list(payload, "playbooks")
+        prompt, system_prompt = _build_prompt(messages, playbooks)
+        content = _run_openclaw_cli(prompt=prompt, system_prompt=system_prompt)
+    except Exception as exc:  # noqa: BLE001 — script errors become LocalScript failures.
+        sys.stderr.write(f"{type(exc).__name__}: {exc}\n")
+        return 1
+
+    json.dump({"content": content}, sys.stdout, ensure_ascii=False)
+    sys.stdout.write("\n")
+    return 0
+
+
+def _read_payload() -> dict[str, Any]:
+    """Read and parse a JSON payload from stdin.
+
+    Returns:
+        dict[str, Any]: Parsed payload.
+
+    Raises:
+        OptimizerAssistantError: If stdin is not valid JSON or not an object.
+    """
+    raw = sys.stdin.read()
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise OptimizerAssistantError("stdin must be a JSON object") from exc
+    if not isinstance(payload, dict):
+        raise OptimizerAssistantError("stdin must be a JSON object")
+    return payload
+
+
+def _validated_list(payload: dict[str, Any], field: str) -> list[Any]:
+    """Return ``payload[field]`` as a list, raising if missing or wrong type."""
+    value = payload.get(field)
+    if not isinstance(value, list):
+        raise OptimizerAssistantError(f"payload.{field} must be a list")
+    return value
+
+
+def _build_prompt(messages: list[Any], playbooks: list[Any]) -> tuple[str, str]:
+    """Build ``(prompt, system_prompt)`` from the optimizer payload.
+
+    Args:
+        messages (list[Any]): Conversation messages from the optimizer.
+        playbooks (list[Any]): Candidate playbook rules to evaluate.
+
+    Returns:
+        tuple[str, str]: ``(prompt, system_prompt)`` for the CLI call.
+
+    Raises:
+        OptimizerAssistantError: If messages contain no content.
+    """
+    normalized = [_normalize_message(message) for message in messages]
+    normalized = [message for message in normalized if message["content"]]
+    if not normalized:
+        raise OptimizerAssistantError("payload.messages must contain content")
+
+    final_message = normalized[-1]
+    prior_messages = normalized[:-1]
+
+    system_sections = [_render_playbooks(playbooks)]
+    existing_system = [
+        message["content"] for message in normalized if message["role"] == "system"
+    ]
+    if existing_system:
+        system_sections.append(
+            "## Existing system context\n" + "\n\n".join(existing_system)
+        )
+
+    prior_dialogue = [
+        message
+        for message in prior_messages
+        if message["role"] in {"user", "assistant"}
+    ]
+    if prior_dialogue:
+        system_sections.append(
+            "## Conversation so far\n" + _render_transcript(prior_dialogue)
+        )
+
+    prompt = final_message["content"]
+    if final_message["role"] != "user":
+        prompt = _render_transcript([final_message])
+    system_prompt = "\n\n".join(section for section in system_sections if section)
+    return prompt, system_prompt
+
+
+def _normalize_message(message: Any) -> dict[str, str]:
+    """Coerce a raw message dict to ``{role, content}`` with safe defaults."""
+    if not isinstance(message, dict):
+        raise OptimizerAssistantError("each message must be an object")
+    role = str(message.get("role") or "user").strip().lower()
+    if role not in {"user", "assistant", "system"}:
+        role = "user"
+    content = message.get("content")
+    if not isinstance(content, str):
+        raise OptimizerAssistantError("each message.content must be a string")
+    return {"role": role, "content": content.strip()}
+
+
+def _render_playbooks(playbooks: list[Any]) -> str:
+    """Render the candidate playbook rules as a markdown section."""
+    if not playbooks:
+        return ""
+    lines = ["## Candidate playbook rules"]
+    for index, playbook in enumerate(playbooks, start=1):
+        if not isinstance(playbook, dict):
+            raise OptimizerAssistantError("each playbook must be an object")
+        content = playbook.get("content")
+        if not isinstance(content, str) or not content.strip():
+            raise OptimizerAssistantError("each playbook.content must be a string")
+        trigger = playbook.get("trigger")
+        suffix = ""
+        if isinstance(trigger, str) and trigger.strip():
+            suffix = f" (when: {trigger.strip()})"
+        lines.append(f"{index}. {content.strip()}{suffix}")
+    return "\n".join(lines)
+
+
+def _render_transcript(messages: list[dict[str, str]]) -> str:
+    """Render a list of normalized messages as a ``Role: content`` transcript."""
+    labels = {"user": "User", "assistant": "Assistant", "system": "System"}
+    return "\n\n".join(
+        f"{labels.get(message['role'], 'User')}: {message['content']}"
+        for message in messages
+    )
+
+
+def _resolve_cli_path() -> str | None:
+    """Return the openclaw binary path, honoring ``OPENCLAW_BIN`` then PATH."""
+    override = os.environ.get(ENV_CLI_PATH)
+    if override and Path(override).is_file() and os.access(override, os.X_OK):
+        return override
+    return shutil.which("openclaw")
+
+
+def _run_openclaw_cli(*, prompt: str, system_prompt: str) -> str:
+    """Invoke ``openclaw infer model run`` and return the completion text.
+
+    Args:
+        prompt (str): User-facing portion of the prompt.
+        system_prompt (str): System context (playbook rules + transcript)
+            concatenated into the same prompt — openclaw does not have a
+            separate ``--system-prompt`` flag.
+
+    Returns:
+        str: Completion text extracted from the CLI's JSON stdout.
+
+    Raises:
+        OptimizerAssistantError: On missing CLI, timeout, non-zero exit, or
+            unparseable JSON output.
+    """
+    cli = _resolve_cli_path()
+    if not cli:
+        raise OptimizerAssistantError("openclaw CLI not found; set OPENCLAW_BIN")
+
+    full_prompt = _join_prompt(prompt=prompt, system_prompt=system_prompt)
+    argv = [cli, "infer", "model", "run", "--prompt", full_prompt, "--json"]
+    model = os.environ.get(ENV_DEFAULT_MODEL)
+    if model:
+        argv += ["--model", model]
+
+    env = os.environ.copy()
+    env["OPENCLAW_SMART_INTERNAL"] = "1"
+    timeout_s = int(os.environ.get(ENV_TIMEOUT, str(_CLI_TIMEOUT_SECONDS)))
+
+    try:
+        proc = subprocess.run(  # noqa: S603 — argv is fully constructed.
+            argv,
+            env=env,
+            capture_output=True,
+            text=True,
+            timeout=timeout_s,
+            check=False,
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise OptimizerAssistantError(
+            f"openclaw CLI timed out after {timeout_s}s"
+        ) from exc
+    except FileNotFoundError as exc:
+        raise OptimizerAssistantError("openclaw CLI not found on PATH") from exc
+
+    if proc.returncode != 0:
+        stderr = proc.stderr.strip()
+        raise OptimizerAssistantError(
+            f"openclaw CLI exited {proc.returncode}: {stderr[:500]}"
+        )
+
+    try:
+        data = json.loads(proc.stdout)
+    except json.JSONDecodeError as exc:
+        raise OptimizerAssistantError(
+            f"openclaw CLI returned non-JSON: {proc.stdout[:200]}"
+        ) from exc
+    if not isinstance(data, dict):
+        raise OptimizerAssistantError("openclaw CLI JSON output must be an object")
+
+    content = _extract_content(data)
+    if not content:
+        raise OptimizerAssistantError(
+            f"openclaw CLI JSON had no completion text: {list(data)[:5]}"
+        )
+    return content
+
+
+def _join_prompt(*, prompt: str, system_prompt: str) -> str:
+    """Concatenate system context above the user prompt."""
+    if not system_prompt:
+        return prompt
+    return f"{system_prompt}\n\n## Task\n{prompt}"
+
+
+def _extract_content(payload: dict[str, Any]) -> str:
+    """Pull the completion text from openclaw's JSON output.
+
+    The exact field name in ``openclaw infer model run --json`` output is not
+    pinned at design time; scan common keys in priority order.
+    """
+    for key in ("text", "content", "output", "result", "response"):
+        value = payload.get(key)
+        if isinstance(value, str) and value:
+            return value
+    msg = payload.get("message")
+    if isinstance(msg, dict) and isinstance(msg.get("content"), str):
+        return msg["content"]
+    return ""
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/plugin/vendor/reflexio/reflexio/integrations/openclaw/plugin/src/openclaw_smart/publish.py

@@ -0,0 +1,96 @@
+"""Publish-to-reflexio orchestration used by agent_end, session_end, and the sync CLI.
+
+One helper — ``publish_unpublished`` — owns the read-buffer → slice → publish →
+stamp-watermark sequence so the three call sites stay in sync. Returns a
+``(status, interaction_count)`` tuple so callers can format appropriate
+messaging without peeking at the adapter.
+"""
+
+from __future__ import annotations
+
+import contextlib
+from collections.abc import Iterator
+from typing import Literal
+
+from openclaw_smart import state
+from openclaw_smart.reflexio_adapter import Adapter
+
+try:
+    import fcntl  # POSIX only — Windows falls back to no publish lock.
+except ImportError:  # pragma: no cover — non-POSIX platforms
+    fcntl = None  # type: ignore[assignment]
+
+PublishStatus = Literal["nothing", "ok", "failed"]
+
+
+@contextlib.contextmanager
+def _session_publish_lock(session_id: str) -> Iterator[None]:
+    """Serialize read-publish-watermark for one session buffer."""
+    lock_path = state.publish_lock_path(session_id)
+    if lock_path is None or fcntl is None:
+        yield
+        return
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    with lock_path.open("a", encoding="utf-8") as fh:
+        fcntl.flock(fh.fileno(), fcntl.LOCK_EX)
+        try:
+            yield
+        finally:
+            fcntl.flock(fh.fileno(), fcntl.LOCK_UN)
+
+
+def publish_unpublished(
+    *,
+    session_id: str,
+    project_id: str,
+    force_extraction: bool,
+    skip_aggregation: bool,
+    adapter: Adapter | None = None,
+) -> tuple[PublishStatus, int]:
+    """Drain the session buffer to reflexio and stamp the high-water mark.
+
+    Args:
+        session_id (str): openClaw session id (``sessionKey``), attached to
+            each interaction.
+        project_id (str): Stable project name; used as reflexio's ``user_id``
+            (preferences) so preferences accumulate at the project level
+            across sessions. ``agent_version`` is hardcoded to ``"openclaw"``
+            in the adapter so skills roll up 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.
+        skip_aggregation (bool): When True, reflexio extracts preferences and
+            raw project-specific skill entries but skips the rollup into
+            shared skills. openclaw-smart passes False on every publish path
+            so ``user_playbooks`` roll up into ``agent_playbooks``;
+            aggregation additionally requires ``aggregation_config`` to be
+            set on reflexio's ``user_playbook_extractor_configs[0]`` and
+            ``optimize_agent_playbooks=true`` at the top level — otherwise
+            the rollup silently no-ops.
+        adapter (Adapter | None): Injection point for tests; a fresh
+            ``Adapter()`` is constructed when omitted.
+
+    Returns:
+        tuple[PublishStatus, int]: ``("nothing", 0)`` if the buffer has no
+            unpublished turns, ``("ok", n)`` after a successful publish of
+            ``n`` interactions, or ``("failed", n)`` if reflexio rejected or
+            was unreachable. On ``"failed"`` the watermark is not advanced,
+            so the next hook retries the same batch.
+    """
+    with _session_publish_lock(session_id):
+        records = state.read_all(session_id)
+        _, interactions = state.unpublished_slice(records)
+        if not interactions:
+            return ("nothing", 0)
+        client = adapter if adapter is not None else Adapter()
+        ok = client.publish(
+            session_id=session_id,
+            project_id=project_id,
+            interactions=interactions,
+            force_extraction=force_extraction,
+            skip_aggregation=skip_aggregation,
+        )
+        if ok:
+            state.append(session_id, {"published_up_to": len(records)})
+            return ("ok", len(interactions))
+        return ("failed", len(interactions))

package/plugin/vendor/reflexio/reflexio/integrations/openclaw/plugin/src/openclaw_smart/query_compose.py

@@ -0,0 +1,66 @@
+"""Compose a reflexio search query from a before_tool_call payload.
+
+Deterministic — no LLM call — so the before_tool_call hook can stay inside
+its latency budget. The output is fed to ``ReflexioClient.search(query=...)``
+(the unified ``/api/search`` endpoint, which fans out to user playbooks,
+agent playbooks, and preferences server-side), which tokenizes via reflexio's
+FTS5 sanitizer (OR-joined, stemmed) plus a vector-similarity leg. Short,
+meaning-dense strings give the most selective hybrid ranking.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+_MAX_SNIPPET_LEN = 400
+
+
+def from_tool_call(tool_name: str, tool_input: Mapping[str, Any]) -> str:
+    """Compose a search query from an openClaw before_tool_call payload.
+
+    Args:
+        tool_name (str): Tool name as reported by openClaw (after
+            camelCase→snake_case translation, e.g. ``"Edit"``, ``"Bash"``).
+        tool_input (Mapping[str, Any]): The tool's input dict as delivered
+            by the hook payload (after camelCase translation).
+
+    Returns:
+        str: A short query suitable for reflexio hybrid search, or ``""``
+            when the tool is not one we compose for (caller should then
+            skip the search entirely).
+    """
+    match tool_name:
+        case "Edit" | "Write" | "NotebookEdit":
+            return _from_file_edit(tool_input)
+        case "Bash":
+            return _from_bash(tool_input)
+        case _:
+            return ""
+
+
+def _as_str(value: Any) -> str:
+    """Coerce a tool-payload field to a string, treating non-strings as empty.
+
+    Tool inputs come from external openClaw payloads; a malformed event with
+    a non-string ``new_string`` or ``command`` would otherwise crash the
+    hook with ``AttributeError`` / ``TypeError``. We prefer a clean empty
+    query over a partial failure.
+    """
+    return value if isinstance(value, str) else ""
+
+
+def _from_file_edit(tool_input: Mapping[str, Any]) -> str:
+    path = _as_str(tool_input.get("file_path"))
+    snippet = _as_str(tool_input.get("new_string")) or _as_str(
+        tool_input.get("content")
+    )
+    basename = Path(path).name if path else ""
+    return f"{basename} {snippet[:_MAX_SNIPPET_LEN]}".strip()
+
+
+def _from_bash(tool_input: Mapping[str, Any]) -> str:
+    command = _as_str(tool_input.get("command"))
+    first_line = command.splitlines()[0] if command else ""
+    return first_line[:_MAX_SNIPPET_LEN].strip()