memgraph-context-graph 0.5.0__py3-none-any.whl

memgraph_context_graph/adapters/antigravity_cli.py

@@ -0,0 +1,152 @@
+"""Antigravity CLI (``agy``) command-hook runtime adapter.
+
+Antigravity hooks expose less than other runtimes: tool calls and their
+errors, model-invocation counters, and execution stops. They carry no tool
+results, prompts, assistant text, or token usage, so an Antigravity session
+records what ran but not what came back.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from memgraph_context_graph.adapters._spec import (
+    EventContext,
+    FieldMap,
+    HookConfig,
+    RuntimeSpec,
+    SpecAdapter,
+    SpecPlugin,
+    event_user_id,
+    json_hook_installer,
+    string_or_none,
+    turn_end,
+)
+from memgraph_context_graph.events import ErrorOccurredEvent, SessionStartEvent, ToolEndEvent, ToolStartEvent
+
+if TYPE_CHECKING:
+    from memgraph_context_graph.events import Event
+
+
+def _workspace(context: EventContext) -> str | None:
+    paths = context.payload.get("workspacePaths")
+    return str(paths[0]) if isinstance(paths, list) and paths else None
+
+
+def _tool_call(context: EventContext) -> dict[str, Any]:
+    tool_call = context.payload.get("toolCall")
+    return tool_call if isinstance(tool_call, dict) else {}
+
+
+def _step_id(context: EventContext) -> str | None:
+    # No tool-call id exists; the trajectory step index is shared by a call's
+    # PreToolUse and PostToolUse, so it pairs them within one conversation.
+    step = context.payload.get("stepIdx")
+    return None if step is None else f"step-{step}"
+
+
+def _session_start(context: EventContext) -> SessionStartEvent | None:
+    # No session-start hook exists. Each turn's first model invocation
+    # (invocationNum resets per turn) stands in for it; connectors ignore a
+    # start for a session they already hold.
+    if context.payload.get("invocationNum") != 0:
+        return None
+    return SessionStartEvent(
+        **context.base(),
+        model=string_or_none(context.payload.get("modelName")),
+        working_directory=_workspace(context),
+        user_id=event_user_id(context),
+    )
+
+
+def _tool_start(context: EventContext) -> ToolStartEvent:
+    tool_call = _tool_call(context)
+    return ToolStartEvent(
+        **context.base(),
+        tool_name=str(tool_call.get("name") or ""),
+        tool_input=tool_call.get("args"),
+        tool_use_id=_step_id(context),
+    )
+
+
+def _tool_end(context: EventContext) -> ToolEndEvent:
+    error = string_or_none(context.payload.get("error")) or None
+    return ToolEndEvent(
+        **context.base(),
+        tool_name=str(_tool_call(context).get("name") or ""),
+        tool_use_id=_step_id(context),
+        is_error=error is not None,
+        error_message=error,
+    )
+
+
+def _stop(context: EventContext) -> list[Event]:
+    # Stop ends one execution loop. agy has no session-end hook, so a loop that
+    # leaves the agent fully idle is the turn end; a failed one is also an error.
+    events: list[Event] = []
+    error = context.payload.get("error")
+    reason = context.payload.get("terminationReason")
+    if error:
+        events.append(
+            ErrorOccurredEvent(
+                **context.base(),
+                error_type=str(reason or "antigravity_error"),
+                error_message=str(error),
+                recoverable=True,
+            )
+        )
+    if context.payload.get("fullyIdle"):
+        events.extend(turn_end(context, reason=reason))
+    return events
+
+
+_HOOKS = ("PreInvocation", "PreToolUse", "PostToolUse", "Stop")
+SPEC = RuntimeSpec(
+    name="antigravity-cli",
+    source_sdk="antigravity-cli",
+    event_key="hook_event_name",
+    hooks=_HOOKS,
+    rules={
+        "PreInvocation": _session_start,
+        "PreToolUse": _tool_start,
+        "PostToolUse": _tool_end,
+        "Stop": _stop,
+    },
+    metadata_keys=(
+        "workspacePaths",
+        "transcriptPath",
+        "artifactDirectoryPath",
+        "modelName",
+        "stepIdx",
+        "invocationNum",
+        "executionNum",
+        "terminationReason",
+        "fullyIdle",
+    ),
+    # hooks.json is keyed by named hook groups; this runtime owns one group.
+    # Only tool events take matcher groups: agy rejects the whole file if a
+    # lifecycle event is nested, so those are written as flat handlers.
+    config=HookConfig(
+        path=".agents/hooks.json",
+        layout="nested",
+        root_key="memgraph-context-graph",
+        merge=True,
+        inject_event_name=True,
+        flat_hooks=frozenset({"PreInvocation", "Stop"}),
+    ),
+    fields=FieldMap(session_id=("conversationId",)),
+    # PostToolUse requires an object; an empty PreToolUse answer leaves agy's
+    # own permission prompt in charge, so capture never approves a tool.
+    responses={"PostToolUse": {}},
+    probe_payload={"hook_event_name": "PreInvocation", "conversationId": "doctor", "invocationNum": 0},
+)
+
+
+class AntigravityCLIHooksAdapter(SpecAdapter):
+    """Convert Antigravity CLI hook payloads into Event Protocol events."""
+
+    SPEC = SPEC
+
+
+init = json_hook_installer(SPEC)
+PLUGIN = SpecPlugin(SPEC, AntigravityCLIHooksAdapter, init=init)

memgraph_context_graph/adapters/claude.py

@@ -0,0 +1,297 @@
+"""Claude Agent SDK adapter for memgraph-context-graph.
+
+Translates Claude Agent SDK hook callbacks into the common Event protocol
+and forwards them to the AgentLink hub.
+
+Note: this adapter only wires up the ``hooks={...}`` callback API. The SDK's
+separate message-stream API (``query()``/``ClaudeSDKClient.receive_response()``,
+yielding ``UserMessage``/``AssistantMessage``) carries a genuine
+``parent_tool_use_id`` field that would let a subagent's spawning tool call be
+linked directly rather than inferred -- verified empirically, not just in
+docs. Deliberately not consumed here: doing so would make this one adapter
+strictly better than the other three (Claude Code, Codex, OpenAI Agents SDK),
+which have no equivalent field and stay on the general temporal/agent_type
+inference rule uniformly. Revisit only if that asymmetry becomes worth
+taking on.
+
+Usage::
+
+    from memgraph_context_graph import AgentLink
+    from memgraph_context_graph.adapters.claude import ClaudeAdapter
+
+    link = AgentLink()
+    adapter = ClaudeAdapter(link, session_id="s-1")
+    hooks = adapter.get_runtime_hooks()
+
+    # Pass hooks to ClaudeAgentOptions
+    options = ClaudeAgentOptions(hooks=hooks)
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, cast
+
+from memgraph_context_graph.events import (
+    AgentEndEvent,
+    AgentStartEvent,
+    ErrorOccurredEvent,
+    MessageEvent,
+    SessionEndEvent,
+    SessionStartEvent,
+    ToolEndEvent,
+    ToolStartEvent,
+)
+from memgraph_context_graph.protocols import RuntimeAdapter
+
+if TYPE_CHECKING:
+    from memgraph_context_graph.link import AgentLink
+
+_SOURCE = "claude"
+
+
+class ClaudeAdapter(RuntimeAdapter):
+    """Adapter that converts Claude Agent SDK hooks into memgraph-context-graph events.
+
+    Args:
+        link: The AgentLink hub to emit events to.
+        session_id: Session identifier for all events.
+        auto_session: If ``True``, emit SessionStartEvent on creation.
+        session_kwargs: Extra fields for SessionStartEvent (model, …).
+    """
+
+    def __init__(
+        self,
+        link: AgentLink,
+        session_id: str,
+        *,
+        auto_session: bool = True,
+        session_kwargs: dict[str, Any] | None = None,
+    ) -> None:
+        self._link = link
+        self._session_id = session_id
+        self._tool_use_to_action: dict[str, str] = {}
+
+        if auto_session:
+            kw = session_kwargs or {}
+            self._link.emit(
+                SessionStartEvent(
+                    session_id=session_id,
+                    source_sdk=_SOURCE,
+                    model=kw.get("model"),
+                    working_directory=kw.get("working_directory"),
+                    user_id=kw.get("user_id"),
+                    metadata=kw.get("metadata", {}),
+                )
+            )
+
+    # ------------------------------------------------------------------
+    # Runtime adapter interface
+    # ------------------------------------------------------------------
+
+    def get_runtime_hooks(self) -> dict[str, list[Any]]:
+        """Return a hooks dict suitable for ``ClaudeAgentOptions(hooks=...)``."""
+        try:
+            from claude_agent_sdk import HookMatcher
+        except ImportError:
+
+            class HookMatcher:  # type: ignore[no-redef]
+                def __init__(
+                    self,
+                    matcher: str | None = None,
+                    hooks: list[Any] | None = None,
+                    timeout: float | None = None,
+                ):
+                    self.matcher = matcher
+                    self.hooks = hooks or []
+                    self.timeout = timeout
+
+        # Our hook callbacks return a permissive dict[str, Any] rather than the
+        # SDK's precise AsyncHookJSONOutput/SyncHookJSONOutput shapes, matching
+        # the try/except HookMatcher shim above: this module treats the SDK as
+        # optional/duck-typed rather than taking a hard type dependency on it.
+        return {
+            "PreToolUse": [HookMatcher(hooks=[cast("Any", self._pre_tool_use)])],
+            "PostToolUse": [HookMatcher(hooks=[cast("Any", self._post_tool_use)])],
+            "PostToolUseFailure": [HookMatcher(hooks=[cast("Any", self._post_tool_use_failure)])],
+            "UserPromptSubmit": [HookMatcher(hooks=[cast("Any", self._user_prompt_submit)])],
+            "SubagentStart": [HookMatcher(hooks=[cast("Any", self._subagent_start)])],
+            "SubagentStop": [HookMatcher(hooks=[cast("Any", self._subagent_stop)])],
+            "Notification": [HookMatcher(hooks=[cast("Any", self._notification)])],
+            "Stop": [HookMatcher(hooks=[cast("Any", self._stop)])],
+        }
+
+    # ------------------------------------------------------------------
+    # Hook callbacks (async, matching Claude SDK signature)
+    # ------------------------------------------------------------------
+
+    async def _pre_tool_use(
+        self,
+        input_data: dict[str, Any],
+        tool_use_id: str | None,
+        _context: dict[str, Any],
+    ) -> dict[str, Any]:
+        tool_name = input_data.get("tool_name", "")
+        tool_input = input_data.get("tool_input", {})
+        actual_id = input_data.get("tool_use_id") or tool_use_id
+
+        self._link.emit(
+            ToolStartEvent(
+                session_id=self._session_id,
+                source_sdk=_SOURCE,
+                tool_name=tool_name,
+                tool_input=tool_input,
+                tool_use_id=actual_id,
+                agent_name=input_data.get("agent_id"),
+                metadata={k: input_data.get(k) for k in ("agent_type", "cwd") if input_data.get(k) is not None},
+            )
+        )
+        return {}
+
+    async def _post_tool_use(
+        self,
+        input_data: dict[str, Any],
+        tool_use_id: str | None,
+        _context: dict[str, Any],
+    ) -> dict[str, Any]:
+        tool_name = input_data.get("tool_name", "")
+        actual_id = input_data.get("tool_use_id") or tool_use_id
+        tool_response = input_data.get("tool_response")
+
+        is_error = False
+        error_message = None
+        content = tool_response
+        if isinstance(tool_response, dict):
+            is_error = tool_response.get("is_error", False)
+            error_message = tool_response.get("error")
+            content = tool_response.get("content", tool_response)
+
+        self._link.emit(
+            ToolEndEvent(
+                session_id=self._session_id,
+                source_sdk=_SOURCE,
+                tool_name=tool_name,
+                tool_use_id=actual_id,
+                result=content,
+                is_error=is_error,
+                error_message=error_message,
+                agent_name=input_data.get("agent_id"),
+            )
+        )
+        return {}
+
+    async def _post_tool_use_failure(
+        self,
+        input_data: dict[str, Any],
+        tool_use_id: str | None,
+        _context: dict[str, Any],
+    ) -> dict[str, Any]:
+        tool_name = input_data.get("tool_name", "")
+        actual_id = input_data.get("tool_use_id") or tool_use_id
+        error = input_data.get("error", "Unknown error")
+
+        self._link.emit(
+            ErrorOccurredEvent(
+                session_id=self._session_id,
+                source_sdk=_SOURCE,
+                error_type="tool_failure",
+                error_message=str(error),
+                error_details={
+                    "tool_name": tool_name,
+                    "tool_use_id": actual_id,
+                    "tool_input": input_data.get("tool_input", {}),
+                    "is_interrupt": input_data.get("is_interrupt", False),
+                },
+                recoverable=not input_data.get("is_interrupt", False),
+            )
+        )
+        return {}
+
+    async def _user_prompt_submit(
+        self,
+        input_data: dict[str, Any],
+        _tool_use_id: str | None,
+        _context: dict[str, Any],
+    ) -> dict[str, Any]:
+        self._link.emit(
+            MessageEvent(
+                session_id=self._session_id,
+                source_sdk=_SOURCE,
+                role="user",
+                content=input_data.get("prompt", ""),
+                agent_name=input_data.get("agent_id"),
+                metadata={k: input_data.get(k) for k in ("cwd", "permission_mode") if input_data.get(k) is not None},
+            )
+        )
+        return {}
+
+    async def _subagent_start(
+        self,
+        input_data: dict[str, Any],
+        _tool_use_id: str | None,
+        _context: dict[str, Any],
+    ) -> dict[str, Any]:
+        self._link.emit(
+            AgentStartEvent(
+                session_id=self._session_id,
+                source_sdk=_SOURCE,
+                agent_name=input_data.get("agent_id", ""),
+                agent_type=input_data.get("agent_type", ""),
+            )
+        )
+        return {}
+
+    async def _subagent_stop(
+        self,
+        input_data: dict[str, Any],
+        _tool_use_id: str | None,
+        _context: dict[str, Any],
+    ) -> dict[str, Any]:
+        self._link.emit(
+            AgentEndEvent(
+                session_id=self._session_id,
+                source_sdk=_SOURCE,
+                agent_name=input_data.get("agent_id", ""),
+                agent_type=input_data.get("agent_type", ""),
+                metadata={
+                    "stop_hook_active": input_data.get("stop_hook_active"),
+                    "agent_transcript_path": input_data.get("agent_transcript_path"),
+                },
+            )
+        )
+        return {}
+
+    async def _notification(
+        self,
+        input_data: dict[str, Any],
+        _tool_use_id: str | None,
+        _context: dict[str, Any],
+    ) -> dict[str, Any]:
+        self._link.emit(
+            MessageEvent(
+                session_id=self._session_id,
+                source_sdk=_SOURCE,
+                role="system",
+                content=input_data.get("message", ""),
+                agent_name=input_data.get("agent_id"),
+                metadata={
+                    "title": input_data.get("title"),
+                    "notification_type": input_data.get("notification_type"),
+                },
+            )
+        )
+        return {}
+
+    async def _stop(
+        self,
+        _input_data: dict[str, Any],
+        _tool_use_id: str | None,
+        _context: dict[str, Any],
+    ) -> dict[str, Any]:
+        self._link.emit(
+            SessionEndEvent(
+                session_id=self._session_id,
+                source_sdk=_SOURCE,
+                status="completed",
+            )
+        )
+        return {}

memgraph_context_graph/adapters/claude_code.py

@@ -0,0 +1,216 @@
+"""Claude Code command-hook runtime adapter."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from memgraph_context_graph.adapters._spec import (
+    EventContext,
+    HookConfig,
+    RuntimeSpec,
+    SpecAdapter,
+    SpecPlugin,
+    pre_tool_use_context,
+    session_start,
+    tool_start,
+    turn_end,
+)
+from memgraph_context_graph.adapters.claude_code_memory import CLAUDE_CODE_MEMORY
+from memgraph_context_graph.events import (
+    AgentEndEvent,
+    AgentStartEvent,
+    ErrorOccurredEvent,
+    MessageEvent,
+    SessionEndEvent,
+    ToolEndEvent,
+)
+
+if TYPE_CHECKING:
+    from memgraph_context_graph.events import Event
+
+
+def _user_prompt(context: EventContext) -> MessageEvent:
+    return MessageEvent(
+        **context.base(),
+        role="user",
+        content=context.value("prompt", ""),
+        agent_name=context.optional_text("agent_id"),
+    )
+
+
+def _tool_result_text(tool_response: Any) -> Any:
+    """Return the text of a Claude Code tool response, or the response unchanged.
+
+    Bash responses carry ``stdout``/``stderr``, and Read responses carry
+    ``file.content``; other tools' structured responses are kept whole.
+    """
+    if not isinstance(tool_response, dict):
+        return tool_response
+    if isinstance(tool_response.get("stdout"), str):
+        stderr = tool_response.get("stderr")
+        return f"{tool_response['stdout']}\n{stderr}" if stderr else tool_response["stdout"]
+    file = tool_response.get("file")
+    if isinstance(file, dict) and isinstance(file.get("content"), str):
+        return file["content"]
+    return tool_response
+
+
+def _tool_end(context: EventContext) -> ToolEndEvent:
+    return ToolEndEvent(
+        **context.base(),
+        tool_name=context.text("tool_name"),
+        tool_use_id=context.optional_text("tool_use_id"),
+        result=_tool_result_text(context.value("tool_result")),
+        agent_name=context.optional_text("agent_id"),
+    )
+
+
+def _tool_failure(context: EventContext) -> ToolEndEvent:
+    return ToolEndEvent(
+        **context.base(),
+        tool_name=context.text("tool_name"),
+        tool_use_id=context.optional_text("tool_use_id"),
+        is_error=True,
+        error_message=context.optional_text("error"),
+        agent_name=context.optional_text("agent_id"),
+    )
+
+
+def _permission(context: EventContext) -> MessageEvent:
+    return MessageEvent(
+        **context.base(),
+        role="system",
+        content=context.text("tool_name", "permission_request"),
+        agent_name=context.optional_text("agent_id"),
+    )
+
+
+def _permission_denied(context: EventContext) -> ErrorOccurredEvent:
+    return ErrorOccurredEvent(
+        **context.base(),
+        error_type="permission_denied",
+        error_message=str(context.payload.get("reason") or "Permission denied"),
+        recoverable=True,
+    )
+
+
+def _agent_start(context: EventContext) -> AgentStartEvent:
+    agent_type = context.text("agent_type")
+    return AgentStartEvent(
+        **context.base(),
+        agent_name=context.text("agent_id", agent_type),
+        agent_type=agent_type,
+    )
+
+
+def _agent_end(context: EventContext) -> AgentEndEvent:
+    agent_type = context.text("agent_type")
+    return AgentEndEvent(
+        **context.base(),
+        agent_name=context.text("agent_id", agent_type),
+        agent_type=agent_type,
+        output=context.payload.get("last_assistant_message"),
+    )
+
+
+def _turn_end(context: EventContext) -> list[Event]:
+    # Stop ends one turn; SessionEnd, registered separately, ends the session.
+    return turn_end(context, reply=context.payload.get("last_assistant_message"))
+
+
+def _session_end(context: EventContext) -> SessionEndEvent:
+    return SessionEndEvent(**context.base(), status="completed")
+
+
+def _stop_failure(context: EventContext) -> ErrorOccurredEvent:
+    error = str(context.payload.get("error") or "unknown")
+    return ErrorOccurredEvent(
+        **context.base(),
+        error_type=error,
+        error_message=str(context.payload.get("error_details") or error or "Claude Code stop failure"),
+        recoverable=True,
+    )
+
+
+_HOOKS = (
+    "SessionStart",
+    "UserPromptSubmit",
+    "UserPromptExpansion",
+    "PreToolUse",
+    "PostToolUse",
+    "PostToolUseFailure",
+    "PermissionRequest",
+    "PermissionDenied",
+    "SubagentStart",
+    "SubagentStop",
+    "Stop",
+    "StopFailure",
+    "SessionEnd",
+)
+SPEC = RuntimeSpec(
+    name="claude-code",
+    source_sdk="claude-code",
+    event_key="hook_event_name",
+    hooks=_HOOKS,
+    rules={
+        "SessionStart": session_start,
+        "UserPromptSubmit": _user_prompt,
+        "UserPromptExpansion": _user_prompt,
+        "PreToolUse": tool_start,
+        "PostToolUse": _tool_end,
+        "PostToolUseFailure": _tool_failure,
+        "PermissionRequest": _permission,
+        "PermissionDenied": _permission_denied,
+        "SubagentStart": _agent_start,
+        "SubagentStop": _agent_end,
+        "Stop": _turn_end,
+        "StopFailure": _stop_failure,
+        "SessionEnd": _session_end,
+    },
+    metadata_keys=(
+        "cwd",
+        "transcript_path",
+        "permission_mode",
+        "tool_name",
+        "tool_input",
+        "tool_use_id",
+        "tool_response",
+        "duration_ms",
+        "error",
+        "error_details",
+        "is_interrupt",
+        "reason",
+        "stop_hook_active",
+        "last_assistant_message",
+        "agent_id",
+        "agent_type",
+        "agent_transcript_path",
+        "command_name",
+        "command_args",
+        "command_source",
+        "expansion_type",
+    ),
+    # Installed by the Claude Code plugin's hooks.json, not a project-local file.
+    config=HookConfig(
+        layout="nested",
+        matchers={
+            hook: "*"
+            for hook in ("PreToolUse", "PostToolUse", "PostToolUseFailure", "PermissionRequest", "PermissionDenied")
+        },
+    ),
+    responses={"Stop": {"continue": True}, "SubagentStop": {"continue": True}},
+    context_before_tool=pre_tool_use_context,
+    # Grok Build also runs .claude/settings.json hooks, with its own payloads
+    # (camelCase duplicates of every field); its grok runtime records those.
+    foreign_payload_keys=frozenset({"hookEventName"}),
+    probe_payload={"hook_event_name": "Stop", "session_id": "doctor"},
+)
+
+
+class ClaudeCodeHooksAdapter(SpecAdapter):
+    """Convert Claude Code command-hook payloads into Event Protocol events."""
+
+    SPEC = SPEC
+
+
+PLUGIN = SpecPlugin(SPEC, ClaudeCodeHooksAdapter, native_memory=CLAUDE_CODE_MEMORY)