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

memgraph_context_graph/adapters/copilot_cli.py

@@ -0,0 +1,236 @@
+"""GitHub Copilot CLI command-hook runtime adapter."""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+from typing import TYPE_CHECKING, Any
+
+from memgraph_context_graph.adapters._spec import (
+    EventContext,
+    HookConfig,
+    RuntimeSpec,
+    SpecAdapter,
+    SpecPlugin,
+    extract_tool_result,
+    json_hook_installer,
+    session_start,
+    tool_start,
+    turn_end,
+)
+from memgraph_context_graph.events import (
+    AgentEndEvent,
+    AgentStartEvent,
+    ErrorOccurredEvent,
+    MessageEvent,
+    SessionEndEvent,
+    ToolEndEvent,
+    ToolStartEvent,
+)
+
+if TYPE_CHECKING:
+    from memgraph_context_graph.events import Event
+
+
+def _session_end(context: EventContext) -> SessionEndEvent:
+    reason = str(
+        context.payload.get("reason")
+        or context.payload.get("stop_reason")
+        or context.payload.get("stopReason")
+        or "completed"
+    )
+    return SessionEndEvent(**context.base(), status="completed" if reason in {"complete", "end_turn"} else reason)
+
+
+def _message(context: EventContext) -> MessageEvent:
+    return MessageEvent(**context.base(), role="user", content=context.value("prompt", ""))
+
+
+def _tool_input(context: EventContext) -> Any:
+    # Native Copilot payloads may carry toolArgs as a JSON-encoded string.
+    tool_input = context.value("tool_input")
+    if isinstance(tool_input, str):
+        try:
+            return json.loads(tool_input)
+        except ValueError:
+            return tool_input
+    return tool_input
+
+
+def _tool_start(context: EventContext) -> ToolStartEvent:
+    return dataclasses.replace(tool_start(context), tool_input=_tool_input(context))
+
+
+def _tool_end(context: EventContext) -> ToolEndEvent:
+    tool_result = context.value("tool_result")
+    result, is_error, error_message = extract_tool_result(tool_result)
+    result_type = (
+        tool_result.get("resultType", tool_result.get("result_type")) if isinstance(tool_result, dict) else None
+    )
+    if result_type not in (None, "success"):
+        is_error = True
+        error_message = error_message or f"Copilot tool result: {result_type}"
+    return _with_tool_input(
+        context,
+        ToolEndEvent(
+            **context.base(),
+            tool_name=context.text("tool_name"),
+            tool_use_id=context.optional_text("tool_use_id"),
+            result=result,
+            is_error=is_error,
+            error_message=error_message,
+        ),
+    )
+
+
+def _tool_failure(context: EventContext) -> ToolEndEvent:
+    return _with_tool_input(
+        context,
+        ToolEndEvent(
+            **context.base(),
+            tool_name=context.text("tool_name"),
+            tool_use_id=context.optional_text("tool_use_id"),
+            is_error=True,
+            error_message=str(context.payload.get("error") or "Tool failed"),
+        ),
+    )
+
+
+def _with_tool_input(context: EventContext, event: ToolEndEvent) -> ToolEndEvent:
+    # Copilot sends no tool call id, so keep the input on the result to tell
+    # repeated calls of the same tool apart.
+    tool_input = _tool_input(context)
+    if tool_input is not None:
+        event.metadata["tool_input"] = tool_input
+    return event
+
+
+def _permission(context: EventContext) -> MessageEvent:
+    return MessageEvent(**context.base(), role="system", content=context.text("tool_name", "permission_request"))
+
+
+def _agent_name(context: EventContext) -> str:
+    # subagentStart carries only agentName; subagentStop adds agentId and
+    # agentType. agentName is the one key both share, so it names the Agent.
+    return str(context.payload.get("agentName") or context.payload.get("agent_name") or context.text("agent_type"))
+
+
+def _agent_start(context: EventContext) -> AgentStartEvent:
+    agent_name = _agent_name(context)
+    return AgentStartEvent(**context.base(), agent_name=agent_name, agent_type=agent_name)
+
+
+def _agent_end(context: EventContext) -> AgentEndEvent:
+    agent_name = _agent_name(context)
+    output = context.payload.get("last_assistant_message", context.payload.get("response"))
+    return AgentEndEvent(
+        **context.base(),
+        agent_name=agent_name,
+        agent_type=context.text("agent_type", agent_name),
+        output=None if output is None else str(output),
+    )
+
+
+def _turn_end(context: EventContext) -> list[Event]:
+    # agentStop ends one turn; sessionEnd ends the session. Its payload carries
+    # no reply text.
+    return turn_end(context, reason=context.payload.get("stopReason", context.payload.get("stop_reason")))
+
+
+def _error(context: EventContext) -> ErrorOccurredEvent:
+    error = context.payload.get("error")
+    error_dict = error if isinstance(error, dict) else {}
+    message = error_dict.get("message", error)
+    details = {"context": context.payload.get("error_context", context.payload.get("errorContext"))}
+    if error_dict.get("stack") is not None:
+        details["stack"] = error_dict["stack"]
+    return ErrorOccurredEvent(
+        **context.base(),
+        error_type=str(error_dict.get("name") or "copilot_error"),
+        error_message=str(message or "Copilot CLI error"),
+        error_details=details,
+        recoverable=bool(context.payload.get("recoverable", True)),
+    )
+
+
+_HOOKS = (
+    "sessionStart",
+    "sessionEnd",
+    "userPromptSubmitted",
+    "preToolUse",
+    "postToolUse",
+    "postToolUseFailure",
+    "permissionRequest",
+    "subagentStart",
+    "subagentStop",
+    "agentStop",
+    "errorOccurred",
+)
+SPEC = RuntimeSpec(
+    name="copilot-cli",
+    source_sdk="copilot-cli",
+    event_key="hook_event_name",
+    hooks=_HOOKS,
+    rules={
+        "sessionStart": session_start,
+        "sessionEnd": _session_end,
+        "userPromptSubmitted": _message,
+        "preToolUse": _tool_start,
+        "postToolUse": _tool_end,
+        "postToolUseFailure": _tool_failure,
+        "permissionRequest": _permission,
+        "subagentStart": _agent_start,
+        "subagentStop": _agent_end,
+        "agentStop": _turn_end,
+        "errorOccurred": _error,
+    },
+    # VS Code-compatible hook files use PascalCase event names.
+    event_aliases={
+        **{hook[0].upper() + hook[1:]: hook for hook in _HOOKS},
+        "UserPromptSubmit": "userPromptSubmitted",
+    },
+    metadata_keys=(
+        "cwd",
+        "timestamp",
+        "source",
+        "transcript_path",
+        "reason",
+        "stop_reason",
+        "tool_name",
+        "tool_input",
+        "agent_id",
+        "agent_type",
+        "agent_name",
+        "agent_display_name",
+        "agent_description",
+        "agentName",
+        "agentDisplayName",
+        "agentDescription",
+        "error_context",
+    ),
+    config=HookConfig(
+        path=".github/hooks/memgraph-context-graph.json",
+        layout="flat",
+        version=1,
+        merge=True,
+        timeout_key="timeoutSec",
+        inject_event_name=True,
+        matchers={
+            "preToolUse": ".*",
+            "postToolUse": ".*",
+            "permissionRequest": ".*",
+            "subagentStart": ".*",
+        },
+    ),
+    probe_payload={"hook_event_name": "sessionEnd", "sessionId": "doctor", "reason": "complete"},
+)
+
+
+class CopilotCLIHooksAdapter(SpecAdapter):
+    """Convert Copilot CLI hook payloads into Event Protocol events."""
+
+    SPEC = SPEC
+
+
+init = json_hook_installer(SPEC)
+PLUGIN = SpecPlugin(SPEC, CopilotCLIHooksAdapter, init=init)

memgraph_context_graph/adapters/cursor.py

@@ -0,0 +1,189 @@
+"""Cursor command-hook runtime adapter."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from memgraph_context_graph.adapters._spec import (
+    EventContext,
+    FieldMap,
+    HookConfig,
+    RuntimeSpec,
+    SpecAdapter,
+    SpecPlugin,
+    event_user_id,
+    json_hook_installer,
+    tool_end,
+    tool_start,
+    turn_end,
+)
+from memgraph_context_graph.events import (
+    AgentEndEvent,
+    AgentStartEvent,
+    MessageEvent,
+    SessionEndEvent,
+    SessionStartEvent,
+    ToolEndEvent,
+)
+
+if TYPE_CHECKING:
+    from memgraph_context_graph.events import Event
+
+
+def _session_start(context: EventContext) -> SessionStartEvent:
+    workspace_roots = context.payload.get("workspace_roots")
+    cwd = workspace_roots[0] if isinstance(workspace_roots, list) and workspace_roots else context.value("cwd")
+    return SessionStartEvent(
+        **context.base(),
+        model=context.optional_text("model"),
+        working_directory=None if cwd is None else str(cwd),
+        user_id=event_user_id(context),
+    )
+
+
+def _session_end(context: EventContext) -> SessionEndEvent:
+    return SessionEndEvent(**context.base(), status=str(context.payload.get("reason") or "completed"))
+
+
+def _user_message(context: EventContext) -> MessageEvent:
+    return MessageEvent(
+        **context.base(),
+        role="user",
+        content=context.value("prompt", ""),
+        model=context.optional_text("model"),
+    )
+
+
+def _assistant_message(context: EventContext) -> MessageEvent:
+    return MessageEvent(
+        **context.base(),
+        role="assistant",
+        content=context.payload.get("text", ""),
+        model=context.optional_text("model"),
+    )
+
+
+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=str(context.payload.get("error_message") or "Cursor tool failed"),
+    )
+
+
+def _agent_start(context: EventContext) -> AgentStartEvent:
+    agent_type = context.text("agent_type")
+    # Cursor's stop payload omits subagent_id. Use subagent_type as the common
+    # lifecycle key and preserve the start-only ID in metadata.
+    return AgentStartEvent(
+        **context.base(),
+        agent_name=agent_type,
+        agent_type=agent_type,
+    )
+
+
+def _agent_end(context: EventContext) -> AgentEndEvent:
+    agent_type = context.text("agent_type")
+    return AgentEndEvent(
+        **context.base(),
+        agent_name=agent_type,
+        agent_type=agent_type,
+        output=str(context.payload.get("summary")) if context.payload.get("summary") is not None else None,
+    )
+
+
+def _turn_end(context: EventContext) -> list[Event]:
+    # stop ends one agent loop; sessionEnd ends the conversation.
+    return turn_end(context, reason=context.payload.get("status"))
+
+
+SPEC = RuntimeSpec(
+    name="cursor",
+    source_sdk="cursor",
+    event_key="hook_event_name",
+    hooks=(
+        "sessionStart",
+        "sessionEnd",
+        "beforeSubmitPrompt",
+        "preToolUse",
+        "postToolUse",
+        "postToolUseFailure",
+        "subagentStart",
+        "subagentStop",
+        "afterAgentResponse",
+        "stop",
+    ),
+    rules={
+        "sessionStart": _session_start,
+        "sessionEnd": _session_end,
+        "beforeSubmitPrompt": _user_message,
+        "preToolUse": tool_start,
+        "postToolUse": tool_end,
+        "postToolUseFailure": _tool_failure,
+        "subagentStart": _agent_start,
+        "subagentStop": _agent_end,
+        "afterAgentResponse": _assistant_message,
+        "stop": _turn_end,
+    },
+    metadata_keys=(
+        "generation_id",
+        "model_id",
+        "model_params",
+        "cursor_version",
+        "workspace_roots",
+        "user_email",
+        "transcript_path",
+        "tool_name",
+        "tool_input",
+        "tool_use_id",
+        "duration",
+        "failure_type",
+        "is_interrupt",
+        "task",
+        "subagent_id",
+        "subagent_type",
+        "description",
+        "status",
+        "duration_ms",
+        "agent_transcript_path",
+    ),
+    config=HookConfig(
+        path=".cursor/hooks.json",
+        layout="flat",
+        version=1,
+        merge=True,
+        timeout_key="timeout",
+        matchers={
+            "preToolUse": "*",
+            "postToolUse": "*",
+            "postToolUseFailure": "*",
+            "subagentStart": "*",
+            "subagentStop": "*",
+        },
+    ),
+    fields=FieldMap(session_id=("conversation_id", "session_id")),
+    # Cursor blocks a permission hook whose output doesn't match its schema, so
+    # these hooks must answer. "allow" is the weakest vote: any other hook's
+    # "deny" or "ask" still wins, so capture never loosens the user's policy.
+    responses={
+        "preToolUse": {"permission": "allow"},
+        "subagentStart": {"permission": "allow"},
+        "beforeSubmitPrompt": {"continue": True},
+    },
+    # Grok Build also runs .cursor/hooks.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": "sessionEnd", "session_id": "doctor", "reason": "completed"},
+)
+
+
+class CursorHooksAdapter(SpecAdapter):
+    """Convert Cursor hook payloads into Event Protocol events."""
+
+    SPEC = SPEC
+
+
+init = json_hook_installer(SPEC)
+PLUGIN = SpecPlugin(SPEC, CursorHooksAdapter, init=init)

memgraph_context_graph/adapters/grok.py

@@ -0,0 +1,187 @@
+"""Grok Build (``grok``) command-hook runtime adapter.
+
+Grok sends each payload field in both camelCase and Claude Code's snake_case,
+so the shared field aliases resolve most of it; only its typed tool results
+and per-turn ``Stop`` need Grok-specific rules.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from memgraph_context_graph.adapters._spec import (
+    EventContext,
+    FieldMap,
+    HookConfig,
+    RuntimeSpec,
+    SpecAdapter,
+    SpecPlugin,
+    json_hook_installer,
+    session_start,
+    tool_start,
+    turn_end,
+)
+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", ""))
+
+
+def _tool_result(tool_response: Any) -> tuple[Any, bool]:
+    """Return a typed Grok tool result's model-facing text and whether it failed.
+
+    Results are tagged by ``type``: shell results carry ``output_for_prompt``
+    and ``exit_code``, file reads carry ``FileContent.content``. Other types
+    are kept whole.
+    """
+    if not isinstance(tool_response, dict):
+        return tool_response, False
+    exit_code = tool_response.get("exit_code")
+    text = tool_response.get("output_for_prompt")
+    if text is None:
+        file_content = tool_response.get("FileContent")
+        text = file_content.get("content") if isinstance(file_content, dict) else None
+    return (tool_response if text is None else text), exit_code not in (None, 0)
+
+
+def _tool_end(context: EventContext) -> ToolEndEvent:
+    result, is_error = _tool_result(context.value("tool_result"))
+    return ToolEndEvent(
+        **context.base(),
+        tool_name=context.text("tool_name"),
+        tool_use_id=context.optional_text("tool_use_id"),
+        result=result,
+        is_error=is_error,
+        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=str(context.payload.get("error") or "Grok tool failed"),
+        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 context.text("tool_name", "Permission denied")),
+        recoverable=True,
+    )
+
+
+def _turn_end(context: EventContext) -> list[Event]:
+    # Stop fires at the end of every turn (reason "end_turn") and once more at
+    # shutdown, right after SessionEnd; only the former ends a turn.
+    reason = context.payload.get("reason")
+    if reason == "shutdown":
+        return []
+    reply = context.payload.get("lastAssistantMessage", context.payload.get("last_assistant_message"))
+    return turn_end(context, reply=reply, reason=reason)
+
+
+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("reason") or error),
+        recoverable=True,
+    )
+
+
+def _session_end(context: EventContext) -> SessionEndEvent:
+    return SessionEndEvent(**context.base(), status="completed")
+
+
+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("lastAssistantMessage", context.payload.get("last_assistant_message")),
+    )
+
+
+_HOOKS = (
+    "SessionStart",
+    "UserPromptSubmit",
+    "PreToolUse",
+    "PostToolUse",
+    "PostToolUseFailure",
+    "PermissionDenied",
+    "SubagentStart",
+    "SubagentStop",
+    "Stop",
+    "StopFailure",
+    "SessionEnd",
+)
+SPEC = RuntimeSpec(
+    name="grok",
+    source_sdk="grok",
+    event_key="hook_event_name",
+    hooks=_HOOKS,
+    rules={
+        "SessionStart": session_start,
+        "UserPromptSubmit": _user_prompt,
+        "PreToolUse": tool_start,
+        "PostToolUse": _tool_end,
+        "PostToolUseFailure": _tool_failure,
+        "PermissionDenied": _permission_denied,
+        "SubagentStart": _agent_start,
+        "SubagentStop": _agent_end,
+        "Stop": _turn_end,
+        "StopFailure": _stop_failure,
+        "SessionEnd": _session_end,
+    },
+    metadata_keys=(
+        "cwd",
+        "workspaceRoot",
+        "permissionMode",
+        "source",
+        "reason",
+        "promptId",
+        "transcriptPath",
+        "durationMs",
+        "isBackgrounded",
+        "toolInputTruncated",
+        "toolResultTruncated",
+        "stopHookActive",
+    ),
+    config=HookConfig(path=".grok/hooks/memgraph-context-graph.json", layout="nested", merge=True),
+    fields=FieldMap(tool_result=("tool_response", "toolResult")),
+    probe_payload={"hook_event_name": "SessionEnd", "session_id": "doctor", "reason": "shutdown"},
+)
+
+
+class GrokHooksAdapter(SpecAdapter):
+    """Convert Grok Build hook payloads into Event Protocol events."""
+
+    SPEC = SPEC
+
+
+init = json_hook_installer(SPEC)
+PLUGIN = SpecPlugin(SPEC, GrokHooksAdapter, init=init)