sovara-claude-code 0.1.0__py3-none-any.whl

sovara_claude_code/__init__.py

@@ -0,0 +1,9 @@
+"""Record Claude Code sessions in Sovara and add relevant lessons to each prompt.
+
+Claude Code runs ``sovara-claude-code hook`` for each hook event (see the plugin in this
+package's ``plugin/`` directory). ``handle(event)`` is the same entry point for tests.
+"""
+
+from sovara_claude_code._hooks import handle
+
+__all__ = ["handle"]

sovara_claude_code/__main__.py

@@ -0,0 +1,28 @@
+"""Command line: ``sovara-claude-code hook`` reads one Claude Code hook event from stdin."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+from sovara_claude_code._hooks import handle
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run a hook and print its output for Claude Code; always exits 0."""
+    args = sys.argv[1:] if argv is None else argv
+    if args != ["hook"]:
+        print("usage: sovara-claude-code hook", file=sys.stderr)
+        return 0
+    try:
+        event = json.loads(sys.stdin.read() or "{}")
+    except ValueError:
+        return 0
+    output = handle(event) if isinstance(event, dict) else None
+    if output:
+        print(output)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

sovara_claude_code/_hooks.py

@@ -0,0 +1,233 @@
+"""Record a Claude Code session in Sovara from its hook events.
+
+Hooks run as separate processes, so the session's recording is shared through a handle
+(``sovara.open_recording``) kept in the session's state file. A hook never blocks Claude Code:
+failures are swallowed and requests retry only briefly.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import logging
+import os
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+import sovara
+from sovara import (
+    ConversationInput,
+    ConversationOutput,
+    ErrorInfo,
+    ErrorOutcome,
+    LlmCall,
+    Message,
+    SuccessOutcome,
+    TextBlock,
+    ToolCall,
+)
+from sovara.integration import flush_recordings, json_value, short_retries
+from sovara_claude_code import _state
+
+logger = logging.getLogger("sovara_claude_code")
+
+# Per-request timeout, so a hook's usual three requests fit in the 15 s Claude Code allows
+# it (hooks/hooks.json).
+REQUEST_TIMEOUT_SECONDS = 4.0
+# How long a hook waits, before exiting, for reports the SDK sends in the background.
+FLUSH_SECONDS = REQUEST_TIMEOUT_SECONDS
+
+# Errors meaning the recording no longer exists. A write token the server no longer knows
+# is a SovaraConfigError with HTTP 403.
+_LOST_RECORDING = {"recording_inactive", "not_found"}
+
+
+def _recording_lost(exc: Exception) -> bool:
+    if isinstance(exc, sovara.SovaraConfigError):
+        return exc.status_code == 403
+    return isinstance(exc, sovara.RecordingError) and exc.code in _LOST_RECORDING
+
+
+def _project_name(event: dict[str, Any]) -> str:
+    configured = os.environ.get("SOVARA_PROJECT", "").strip()
+    return configured or Path(str(event.get("cwd") or os.getcwd())).name or "claude-code"
+
+
+def _text_message(role: str, text: str) -> Message:
+    return Message(role=role, content=(TextBlock(text=text),))  # type: ignore[arg-type]
+
+
+def _open(event: dict[str, Any], http_client: httpx.Client | None) -> str:
+    """Open a recording of the session's trace; the same session always gets the same trace."""
+    return sovara.open_recording(
+        project_name=_project_name(event),
+        name="Claude Code session",
+        trace_id=f"claude-code:{event['session_id']}",
+        agent_token=os.environ.get("SOVARA_AGENT_TOKEN") or None,
+        http_client=http_client,
+    )
+
+
+def session_start(event: dict[str, Any], http_client: httpx.Client | None = None) -> str | None:
+    """Open the session's recording, or keep it on resume, clear and compact."""
+    session_id = event["session_id"]
+    _state.prune()
+    if _state.load(session_id) is not None:
+        return None
+    _state.save(session_id, {"session": _open(event, http_client), "turn": None, "prompt": None})
+    return None
+
+
+def _start_turn(session: str, prompt: str, http_client: httpx.Client | None) -> str | None:
+    with sovara.resume_recording(session, http_client=http_client):
+        sovara.start_turn(turn_input=prompt)
+        return sovara.export_recording()
+
+
+def _lessons(handle: str, prompt: str, http_client: httpx.Client | None) -> Any:
+    # Retrieved, not applied: Claude Code does not show what reaches the model.
+    with sovara.resume_recording(handle, http_client=http_client):
+        return sovara.retrieve_lessons(prompt)
+
+
+def user_prompt_submit(
+    event: dict[str, Any], http_client: httpx.Client | None = None
+) -> str | None:
+    """Start a turn for the prompt and return matching lessons as extra context."""
+    session_id = event["session_id"]
+    state = _state.load(session_id)
+    if state is None:
+        # SessionStart could not open the recording; the trace key is stable, so open it now.
+        state = {"session": _open(event, http_client), "turn": None, "prompt": None}
+        _state.save(session_id, state)
+    prompt = str(event.get("prompt") or "")
+    try:
+        turn = _start_turn(state["session"], prompt, http_client)
+    except (sovara.RecordingError, sovara.SovaraConfigError) as exc:
+        # Only a recording the exec server lost (e.g. after a restart) is reopened; a passing
+        # failure must not open a second recording of the session.
+        if not _recording_lost(exc):
+            raise
+        state = {**state, "session": _open(event, http_client)}
+        turn = _start_turn(state["session"], prompt, http_client)
+    # Saved before retrieving lessons, so later steps join this turn even if retrieval fails.
+    _state.save(session_id, {**state, "turn": turn, "prompt": prompt})
+    try:
+        lessons = _lessons(turn or state["session"], prompt, http_client) if prompt else None
+    except sovara.RecordingError:
+        lessons = None
+    if lessons is None:
+        return None
+    return json.dumps(
+        {
+            "hookSpecificOutput": {
+                "hookEventName": "UserPromptSubmit",
+                "additionalContext": lessons.text,
+            }
+        }
+    )
+
+
+def _record(
+    state: dict[str, Any], call: Any, outcome: Any, http_client: httpx.Client | None
+) -> None:
+    handle = state.get("turn") or state["session"]
+    with sovara.resume_recording(handle, http_client=http_client):
+        sovara.record_step(call, outcome)
+
+
+def _tool_call(event: dict[str, Any]) -> ToolCall:
+    arguments = json_value(event.get("tool_input"))
+    return ToolCall(
+        name=str(event.get("tool_name") or "tool"),
+        arguments=arguments if isinstance(arguments, dict) else {"input": arguments},
+        call_id=str(event.get("tool_use_id") or "").strip() or None,
+        metadata={"source": "claude-code"},
+    )
+
+
+def post_tool_use(event: dict[str, Any], http_client: httpx.Client | None = None) -> str | None:
+    """Record a tool call that succeeded."""
+    state = _state.load(event["session_id"])
+    if state is not None:
+        outcome = SuccessOutcome(output=json_value(event.get("tool_response")))
+        _record(state, _tool_call(event), outcome, http_client)
+    return None
+
+
+def post_tool_use_failure(
+    event: dict[str, Any], http_client: httpx.Client | None = None
+) -> str | None:
+    """Record a tool call that failed or was interrupted."""
+    state = _state.load(event["session_id"])
+    if state is not None:
+        error = ErrorInfo(type="ToolError", message=str(event.get("error") or ""))
+        _record(state, _tool_call(event), ErrorOutcome(error=error), http_client)
+    return None
+
+
+def stop(event: dict[str, Any], http_client: httpx.Client | None = None) -> str | None:
+    """Record Claude's reply to the turn's prompt as a model step."""
+    state = _state.load(event["session_id"])
+    reply = str(event.get("last_assistant_message") or "")
+    if state is None or not reply or event.get("stop_hook_active"):
+        return None
+    prompt = str(state.get("prompt") or "")
+    call = LlmCall(
+        provider="anthropic",
+        input=ConversationInput(messages=(_text_message("user", prompt),) if prompt else ()),
+        metadata={"source": "claude-code"},
+    )
+    outcome = SuccessOutcome(output=ConversationOutput(message=_text_message("assistant", reply)))
+    _record(state, call, outcome, http_client)
+    return None
+
+
+def session_end(event: dict[str, Any], http_client: httpx.Client | None = None) -> str | None:
+    """Close the session's recording and forget its state."""
+    session_id = event["session_id"]
+    state = _state.load(session_id)
+    if state is None:
+        return None
+    try:
+        sovara.close_recording(state["session"], http_client=http_client)
+    finally:
+        _state.delete(session_id)
+    return None
+
+
+HANDLERS = {
+    "SessionStart": session_start,
+    "UserPromptSubmit": user_prompt_submit,
+    "PostToolUse": post_tool_use,
+    "PostToolUseFailure": post_tool_use_failure,
+    "Stop": stop,
+    "SessionEnd": session_end,
+}
+
+
+def handle(event: dict[str, Any], http_client: httpx.Client | None = None) -> str | None:
+    """Run the handler for one hook event; return text for Claude Code, or None.
+
+    Never raises: a failure is logged by type only and the session continues unrecorded.
+    """
+    handler = HANDLERS.get(str(event.get("hook_event_name")))
+    if handler is None or not event.get("session_id"):
+        return None
+    try:
+        with short_retries(), contextlib.ExitStack() as stack:
+            if http_client is None:
+                http_client = stack.enter_context(httpx.Client(timeout=REQUEST_TIMEOUT_SECONDS))
+            output = handler(event, http_client)
+            # Reports queued in the background use http_client, which closes on return.
+            flush_recordings(FLUSH_SECONDS)
+            return output
+    except Exception as exc:
+        logger.warning(
+            "Sovara Claude Code hook failed event=%s error_type=%s",
+            event.get("hook_event_name"),
+            type(exc).__name__,
+        )
+        return None

sovara_claude_code/_state.py

@@ -0,0 +1,73 @@
+"""Per-session state shared by the hook processes of one Claude Code session.
+
+Each session has one JSON file holding its recording handles, which carry a write token: the
+file is private (0600), written atomically, and never logged. The format is shared with the
+TypeScript integration (``@sovara/claude-code``).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import tempfile
+import time
+from pathlib import Path
+from typing import Any
+
+# A session whose SessionEnd never ran (a crash) is forgotten after this long.
+STALE_AFTER_SECONDS = 7 * 24 * 3600
+_SAFE_ID = re.compile(r"^[A-Za-z0-9_-]{1,128}$")
+
+
+def state_dir() -> Path:
+    """Return the state directory: the plugin's data directory, else ``~/.sovara/claude-code``."""
+    plugin_data = os.environ.get("CLAUDE_PLUGIN_DATA", "").strip()
+    if plugin_data:
+        return Path(plugin_data)
+    return Path.home() / ".sovara" / "claude-code"
+
+
+def _path(session_id: str) -> Path:
+    if not _SAFE_ID.match(session_id):
+        raise ValueError("Unsupported Claude Code session ID.")
+    return state_dir() / f"{session_id}.json"
+
+
+def load(session_id: str) -> dict[str, Any] | None:
+    """Return the session's state, or None when it has none."""
+    try:
+        return json.loads(_path(session_id).read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return None
+
+
+def save(session_id: str, state: dict[str, Any]) -> None:
+    """Replace the session's state atomically, readable only by the current user."""
+    path = _path(session_id)
+    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+    fd, tmp = tempfile.mkstemp(dir=path.parent, prefix=".tmp-")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as file:
+            json.dump(state, file)
+        os.chmod(tmp, 0o600)
+        os.replace(tmp, path)
+    except BaseException:
+        Path(tmp).unlink(missing_ok=True)
+        raise
+
+
+def delete(session_id: str) -> None:
+    """Forget the session's state."""
+    _path(session_id).unlink(missing_ok=True)
+
+
+def prune() -> None:
+    """Delete state files of sessions that ended without SessionEnd."""
+    cutoff = time.time() - STALE_AFTER_SECONDS
+    for path in state_dir().glob("*.json"):
+        try:
+            if path.stat().st_mtime < cutoff:
+                path.unlink()
+        except OSError:
+            continue

sovara_claude_code-0.1.0.dist-info/METADATA

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: sovara-claude-code
+Version: 0.1.0
+Summary: Record Claude Code sessions in Sovara and add relevant lessons to each prompt
+License-Expression: MIT
+Project-URL: Documentation, https://docs.sovara-labs.com/integrations/claude-code
+Project-URL: Repository, https://github.com/SovaraLabs/sovara-claude-code/tree/main/python
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sovara<0.11,>=0.10
+Dynamic: license-file
+
+# sovara-claude-code
+
+The Python hook program for [Sovara for Claude Code](https://github.com/SovaraLabs/sovara-claude-code#readme).
+
+```sh
+uv tool install sovara-claude-code
+# or: pip install sovara-claude-code
+```
+
+Then load the `sovara-recording` plugin.
+
+## License
+
+MIT.

sovara_claude_code-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+sovara_claude_code/__init__.py,sha256=hVA9WA0aYotV80afQep2KvRWtMhWiSAOQSA9pqxjnio,331
+sovara_claude_code/__main__.py,sha256=ZmABKZCT2PSVbZbs5NFxATvXwasVbWseLZkMU8E9o9Y,747
+sovara_claude_code/_hooks.py,sha256=sXown-DTDdxUbL9ljnldOrRyau7RsNeUphDe_4WW50A,8737
+sovara_claude_code/_state.py,sha256=CjxbmPGnCJ8PkAvCxRAmQ4QBsM2QJHfHsyXqe2IcXmI,2350
+sovara_claude_code-0.1.0.dist-info/licenses/LICENSE,sha256=pHqKd1w5Do29Q1QUMye-4Tz6olJxRgwzNYqcjjfN524,1068
+sovara_claude_code-0.1.0.dist-info/METADATA,sha256=ei8tu6TJCSpHKqar_v0Q2QPDnIwuaw9N0LUIPXM9CfM,765
+sovara_claude_code-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+sovara_claude_code-0.1.0.dist-info/entry_points.txt,sha256=6b7vUYeWpouL4cpRZhrNnBMxO49XH8B1fpcopXfY1o8,72
+sovara_claude_code-0.1.0.dist-info/top_level.txt,sha256=mcRSgbLP5u5910l7XJHYHzeILjXPrsba_1jfjvjfKTE,19
+sovara_claude_code-0.1.0.dist-info/RECORD,,

sovara_claude_code-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

sovara_claude_code-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sovara-claude-code = sovara_claude_code.__main__:main

sovara_claude_code-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sovara Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sovara_claude_code-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sovara_claude_code