execweave 0.6.0__py3-none-any.whl

execweave/cursor_adapter.py

@@ -0,0 +1,347 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import sys
+import time
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+_MAX_COMMAND_CHARS = 4096
+_MAX_LABEL_CHARS = 160
+_SUPPORTED_EVENTS = {"sessionStart", "preToolUse", "postToolUse", "postToolUseFailure"}
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def _entity(
+    entity_type: str,
+    entity_id: str,
+    *,
+    name: str | None = None,
+    attributes: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    return {"type": entity_type, "id": entity_id, "name": name, "attributes": attributes or {}}
+
+
+def _event(
+    *,
+    timestamp: str,
+    event_type: str,
+    relation: str,
+    source: dict[str, Any],
+    target: dict[str, Any],
+    attributes: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    merged = {
+        "backend": "semantic",
+        "attribution": "cursor_hook",
+        "evidence_source": "provider_hook",
+        "provider": "cursor",
+        "causal": False,
+    }
+    if attributes:
+        merged.update(attributes)
+    return {
+        "timestamp": timestamp,
+        "event_type": event_type,
+        "relation": relation,
+        "source": source,
+        "target": target,
+        "attributes": merged,
+    }
+
+
+def _clean_text(value: object, *, limit: int) -> tuple[str | None, bool]:
+    if not isinstance(value, str):
+        return None, False
+    text = value.replace("\x00", "")
+    return (text, False) if len(text) <= limit else (text[:limit], True)
+
+
+def _agent() -> dict[str, Any]:
+    return _entity("agent", "agent:Cursor", name="Cursor")
+
+
+def _scope(payload: dict[str, Any]) -> str:
+    for key in ("conversation_id", "session_id", "generation_id"):
+        value = payload.get(key)
+        if isinstance(value, str) and value:
+            return value
+    return "unknown"
+
+
+def _common_attributes(payload: dict[str, Any]) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for key in (
+        "conversation_id",
+        "generation_id",
+        "session_id",
+        "cursor_version",
+        "cwd",
+        "model",
+        "model_id",
+    ):
+        value = payload.get(key)
+        if isinstance(value, (str, int, float, bool)) and value != "":
+            result[f"cursor_{key}"] = value
+    roots = payload.get("workspace_roots")
+    if isinstance(roots, list):
+        result["cursor_workspace_root_count"] = len(roots)
+    return result
+
+
+def _tool_entity(tool_name: str) -> dict[str, Any]:
+    if tool_name.startswith("MCP:"):
+        native = tool_name[4:] or tool_name
+        return _entity(
+            "tool",
+            f"tool:cursor:mcp:{native}",
+            name=native,
+            attributes={
+                "provider": "cursor",
+                "native_name": tool_name,
+                "mcp_tool": True,
+                "mcp_server_identity_available": False,
+            },
+        )
+    return _entity(
+        "tool",
+        f"tool:cursor:{tool_name}",
+        name=tool_name,
+        attributes={"provider": "cursor", "native_name": tool_name},
+    )
+
+
+def _tool_call_entity(payload: dict[str, Any], tool_name: str) -> dict[str, Any]:
+    tool_use_id = payload.get("tool_use_id")
+    if not isinstance(tool_use_id, str) or not tool_use_id:
+        raise ValueError("Cursor tool hook requires tool_use_id")
+    attrs = _common_attributes(payload)
+    attrs.update({"provider": "cursor", "tool_name": tool_name, "tool_use_id": tool_use_id})
+    tool_input = payload.get("tool_input")
+    if isinstance(tool_input, dict):
+        attrs["input_keys"] = sorted(str(key) for key in tool_input)
+    return _entity(
+        "tool_call",
+        f"tool-call:cursor:{_scope(payload)}:{tool_use_id}",
+        name=tool_name,
+        attributes=attrs,
+    )
+
+
+def _command_entity(tool_input: dict[str, Any]) -> dict[str, Any] | None:
+    command, truncated = _clean_text(tool_input.get("command"), limit=_MAX_COMMAND_CHARS)
+    if not command:
+        return None
+    digest = hashlib.sha256(command.encode("utf-8", errors="replace")).hexdigest()
+    label, _ = _clean_text(command.replace("\n", " "), limit=_MAX_LABEL_CHARS)
+    return _entity(
+        "command",
+        f"command:sha256:{digest}",
+        name=label,
+        attributes={"command": command, "truncated": truncated},
+    )
+
+
+def _declared_file_entity(payload: dict[str, Any], tool_input: dict[str, Any]) -> dict[str, Any] | None:
+    raw = tool_input.get("file_path")
+    if not isinstance(raw, str) or not raw:
+        raw = tool_input.get("path")
+    if not isinstance(raw, str) or not raw:
+        return None
+    candidate = Path(raw).expanduser()
+    if not candidate.is_absolute():
+        cwd = payload.get("cwd")
+        if not isinstance(cwd, str) or not cwd:
+            cwd = tool_input.get("working_directory")
+        if isinstance(cwd, str) and cwd:
+            candidate = Path(cwd) / candidate
+    try:
+        normalized = candidate.resolve(strict=False)
+    except OSError:
+        normalized = candidate.absolute()
+    return _entity(
+        "file",
+        f"file:{normalized}",
+        name=normalized.name or str(normalized),
+        attributes={"declared_by_provider_hook": True, "provider": "cursor"},
+    )
+
+
+def _session_start_events(payload: dict[str, Any], *, timestamp: str) -> list[dict[str, Any]]:
+    model = payload.get("model_id")
+    if not isinstance(model, str) or not model:
+        model = payload.get("model")
+    if not isinstance(model, str) or not model:
+        return []
+    return [
+        _event(
+            timestamp=timestamp,
+            event_type="semantic.cursor.model.observed",
+            relation="USED_MODEL",
+            source=_agent(),
+            target=_entity(
+                "model",
+                f"model:cursor:{model}",
+                name=model,
+                attributes={"provider": "cursor"},
+            ),
+            attributes=_common_attributes(payload),
+        )
+    ]
+
+
+def _pre_tool_events(payload: dict[str, Any], *, timestamp: str) -> list[dict[str, Any]]:
+    tool_name = payload.get("tool_name")
+    if not isinstance(tool_name, str) or not tool_name:
+        raise ValueError("Cursor preToolUse requires tool_name")
+    call = _tool_call_entity(payload, tool_name)
+    tool = _tool_entity(tool_name)
+    common = _common_attributes(payload)
+    events = [
+        _event(
+            timestamp=timestamp,
+            event_type="semantic.cursor.tool.requested",
+            relation="REQUESTED_TOOL_CALL",
+            source=_agent(),
+            target=call,
+            attributes=common,
+        ),
+        _event(
+            timestamp=timestamp,
+            event_type="semantic.cursor.tool.selected",
+            relation="USES_TOOL",
+            source=call,
+            target=tool,
+            attributes=common,
+        ),
+    ]
+    tool_input = payload.get("tool_input")
+    if isinstance(tool_input, dict):
+        if tool_name == "Shell":
+            command = _command_entity(tool_input)
+            if command is not None:
+                events.append(
+                    _event(
+                        timestamp=timestamp,
+                        event_type="semantic.cursor.command.declared",
+                        relation="DECLARED_COMMAND",
+                        source=call,
+                        target=command,
+                        attributes=common,
+                    )
+                )
+        if tool_name in {"Read", "Write", "Delete"}:
+            target = _declared_file_entity(payload, tool_input)
+            if target is not None:
+                events.append(
+                    _event(
+                        timestamp=timestamp,
+                        event_type="semantic.cursor.file.declared",
+                        relation="DECLARED_TARGET",
+                        source=call,
+                        target=target,
+                        attributes=common,
+                    )
+                )
+    return events
+
+
+def _tool_result_events(
+    payload: dict[str, Any],
+    *,
+    timestamp: str,
+    success: bool,
+) -> list[dict[str, Any]]:
+    tool_name = payload.get("tool_name")
+    if not isinstance(tool_name, str) or not tool_name:
+        raise ValueError("Cursor tool result hook requires tool_name")
+    call = _tool_call_entity(payload, tool_name)
+    attrs = _common_attributes(payload)
+    if not success:
+        attrs["provider_reported_failure"] = True
+    return [
+        _event(
+            timestamp=timestamp,
+            event_type=(
+                "semantic.cursor.tool.returned" if success else "semantic.cursor.tool.failed"
+            ),
+            relation="TOOL_CALL_RETURNED" if success else "TOOL_CALL_FAILED",
+            source=call,
+            target=_tool_entity(tool_name),
+            attributes=attrs,
+        )
+    ]
+
+
+def cursor_hook_to_semantic_events(
+    payload: dict[str, Any],
+    *,
+    timestamp: str | None = None,
+) -> list[dict[str, Any]]:
+    hook_event = payload.get("hook_event_name")
+    if not isinstance(hook_event, str) or not hook_event:
+        raise ValueError("Cursor hook payload requires hook_event_name")
+    if hook_event not in _SUPPORTED_EVENTS:
+        return []
+    observed_at = timestamp or _now()
+    if hook_event == "sessionStart":
+        return _session_start_events(payload, timestamp=observed_at)
+    if hook_event == "preToolUse":
+        return _pre_tool_events(payload, timestamp=observed_at)
+    if hook_event == "postToolUse":
+        return _tool_result_events(payload, timestamp=observed_at, success=True)
+    if hook_event == "postToolUseFailure":
+        return _tool_result_events(payload, timestamp=observed_at, success=False)
+    return []
+
+
+def append_semantic_records(path: str | Path, records: list[dict[str, Any]]) -> Path:
+    output = Path(path).expanduser().resolve()
+    output.parent.mkdir(parents=True, exist_ok=True)
+    if not records:
+        return output
+    blob = "".join(
+        json.dumps(record, ensure_ascii=False, sort_keys=True, separators=(",", ":")) + "\n"
+        for record in records
+    )
+    lock_dir = output.with_name(output.name + ".lock")
+    deadline = time.monotonic() + 5.0
+    while True:
+        try:
+            lock_dir.mkdir()
+            break
+        except FileExistsError:
+            if time.monotonic() >= deadline:
+                raise TimeoutError(f"timed out waiting for semantic sidecar lock: {lock_dir}")
+            time.sleep(0.01)
+    try:
+        with output.open("a", encoding="utf-8", newline="\n") as handle:
+            handle.write(blob)
+            handle.flush()
+            os.fsync(handle.fileno())
+    finally:
+        try:
+            lock_dir.rmdir()
+        except OSError:
+            pass
+    return output
+
+
+def read_hook_payload(stream: Any = None) -> dict[str, Any]:
+    source = stream if stream is not None else sys.stdin
+    raw = source.read()
+    if not isinstance(raw, str) or not raw.strip():
+        raise ValueError("Cursor hook stdin is empty")
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"Cursor hook stdin is invalid JSON: {exc.msg}") from exc
+    if not isinstance(payload, dict):
+        raise ValueError("Cursor hook stdin must be one JSON object")
+    return payload

execweave/cursor_hook_cli.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+from .cursor_adapter import append_semantic_records, cursor_hook_to_semantic_events, read_hook_payload
+
+
+def cursor_hook_config(command: str = "execweave-cursor-hook") -> dict[str, Any]:
+    handler = {"command": command}
+    return {
+        "version": 1,
+        "hooks": {
+            "sessionStart": [handler],
+            "preToolUse": [handler],
+            "postToolUse": [handler],
+            "postToolUseFailure": [handler],
+        },
+    }
+
+
+def _default_sidecar(payload: dict[str, Any]) -> Path:
+    cwd = payload.get("cwd")
+    if not isinstance(cwd, str) or not cwd:
+        roots = payload.get("workspace_roots")
+        if isinstance(roots, list) and roots and isinstance(roots[0], str):
+            cwd = roots[0]
+    if not isinstance(cwd, str) or not cwd:
+        raise ValueError("Cursor hook payload has no cwd/workspace root for sidecar placement")
+    scope = None
+    for key in ("conversation_id", "session_id", "generation_id"):
+        value = payload.get(key)
+        if isinstance(value, str) and value:
+            scope = value
+            break
+    if scope is None:
+        raise ValueError("Cursor hook payload has no conversation/session identifier")
+    safe_scope = "".join(
+        character if character.isalnum() or character in {"-", "_", "."} else "_"
+        for character in scope
+    )
+    return Path(cwd) / ".execweave" / "semantic" / "cursor" / f"{safe_scope}.jsonl"
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="execweave-cursor-hook",
+        description="Capture Cursor hook input as local ExecWeave semantic telemetry.",
+    )
+    parser.add_argument("--sidecar", type=Path, default=None)
+    parser.add_argument("--strict", action="store_true")
+    parser.add_argument("--print-config", action="store_true")
+    parser.add_argument("--command", default="execweave-cursor-hook")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.print_config:
+        print(json.dumps(cursor_hook_config(args.command), indent=2, sort_keys=True))
+        return 0
+    try:
+        payload = read_hook_payload()
+        sidecar = args.sidecar
+        if sidecar is None:
+            configured = os.environ.get("EXECWEAVE_SEMANTIC_SIDECAR")
+            sidecar = Path(configured) if configured else _default_sidecar(payload)
+        append_semantic_records(sidecar, cursor_hook_to_semantic_events(payload))
+    except (OSError, TimeoutError, ValueError) as exc:
+        print(f"ExecWeave Cursor hook warning: {exc}", file=sys.stderr)
+        if args.strict:
+            return 1
+    print("{}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

execweave/cursor_record.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from .backends import BackendName
+from .provider_record import ProviderRecordResult, record_provider_to_viewer
+
+CursorRecordResult = ProviderRecordResult
+
+
+def record_cursor_to_viewer(
+    command: list[str],
+    *,
+    watch_root: str | Path,
+    output_dir: str | Path | None = None,
+    backend: BackendName = "auto",
+    poll_interval: float = 0.10,
+    collect_filesystem: bool = True,
+    collect_network: bool = True,
+    keep_raw_trace: bool = False,
+    correlation_window_ms: int = 3000,
+    open_browser: bool = False,
+) -> CursorRecordResult:
+    return record_provider_to_viewer(
+        command,
+        provider_name="Cursor",
+        watch_root=watch_root,
+        output_dir=output_dir,
+        backend=backend,
+        poll_interval=poll_interval,
+        collect_filesystem=collect_filesystem,
+        collect_network=collect_network,
+        keep_raw_trace=keep_raw_trace,
+        correlation_window_ms=correlation_window_ms,
+        open_browser=open_browser,
+    )
+
+
+def _clean_command(command: list[str]) -> list[str]:
+    result = list(command)
+    if result and result[0] == "--":
+        result = result[1:]
+    return result
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="execweave-cursor-record",
+        description=(
+            "Record runtime evidence, Cursor hook telemetry, and conservative "
+            "Tool-to-Process correlation in one local run."
+        ),
+    )
+    parser.add_argument("--watch-root", type=Path, default=None)
+    parser.add_argument("--output-dir", type=Path, default=None)
+    parser.add_argument("--interval", type=float, default=0.10)
+    parser.add_argument("--backend", choices=["auto", "portable", "strace"], default="auto")
+    parser.add_argument("--correlation-window-ms", type=int, default=3000)
+    parser.add_argument("--no-files", action="store_true")
+    parser.add_argument("--no-network", action="store_true")
+    parser.add_argument("--keep-native-trace", action="store_true")
+    parser.add_argument("--open", action="store_true", dest="open_browser")
+    parser.add_argument("command", nargs=argparse.REMAINDER)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    command = _clean_command(args.command)
+    if not command:
+        parser.error("a Cursor command is required, e.g. execweave-cursor-record --open -- cursor")
+    watch_root = (args.watch_root or Path.cwd()).expanduser().resolve()
+    try:
+        result = record_cursor_to_viewer(
+            command,
+            watch_root=watch_root,
+            output_dir=args.output_dir,
+            backend=args.backend,
+            poll_interval=args.interval,
+            collect_filesystem=not args.no_files,
+            collect_network=not args.no_network,
+            keep_raw_trace=args.keep_native_trace,
+            correlation_window_ms=args.correlation_window_ms,
+            open_browser=args.open_browser,
+        )
+    except (FileExistsError, RuntimeError, ValueError, OSError) as exc:
+        parser.error(str(exc))
+    print(json.dumps(result.to_dict(), indent=2, sort_keys=True))
+    return result.runtime.return_code
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

execweave/filesystem.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Iterable
+
+from watchdog.events import FileSystemEvent, FileSystemEventHandler
+from watchdog.observers import Observer
+
+from .schema import Entity, RuntimeEvent
+from .sink import JsonlSink
+
+
+class SessionFileEventHandler(FileSystemEventHandler):
+    """Record filesystem changes observed inside a watched session directory.
+
+    Phase 1 intentionally records these as session-level observations. A filesystem
+    change is not attributed to a specific process until a lower-level collector
+    (for example eBPF/ETW) can prove that relationship.
+    """
+
+    def __init__(
+        self,
+        *,
+        session_id: str,
+        session_entity: Entity,
+        sink: JsonlSink,
+        excluded_roots: Iterable[Path] = (),
+    ) -> None:
+        super().__init__()
+        self.session_id = session_id
+        self.session_entity = session_entity
+        self.sink = sink
+        self.excluded_roots = tuple(path.resolve() for path in excluded_roots)
+
+    def _excluded(self, path: str) -> bool:
+        candidate = Path(path).expanduser().resolve()
+        return any(candidate == root or root in candidate.parents for root in self.excluded_roots)
+
+    def _emit(self, event: FileSystemEvent) -> None:
+        if self._excluded(event.src_path):
+            return
+
+        src = Path(event.src_path).expanduser().resolve()
+        target_path = src
+        attributes: dict[str, object] = {
+            "filesystem_event": event.event_type,
+            "is_directory": event.is_directory,
+            "attribution": "session_observation",
+            "causal": False,
+        }
+
+        destination = getattr(event, "dest_path", None)
+        if destination:
+            dest = Path(destination).expanduser().resolve()
+            if self._excluded(str(dest)):
+                return
+            attributes["source_path"] = str(src)
+            attributes["destination_path"] = str(dest)
+            target_path = dest
+
+        entity_type = "directory" if event.is_directory else "file"
+        target = Entity(type=entity_type, id=f"{entity_type}:{target_path}", name=target_path.name)
+        self.sink.emit(
+            RuntimeEvent.create(
+                session_id=self.session_id,
+                event_type=f"filesystem.{event.event_type}",
+                relation="OBSERVED_FILE_CHANGE",
+                source=self.session_entity,
+                target=target,
+                attributes=attributes,
+            )
+        )
+
+    def on_any_event(self, event: FileSystemEvent) -> None:
+        self._emit(event)
+
+
+class FileWatcher:
+    def __init__(
+        self,
+        *,
+        root: Path,
+        session_id: str,
+        session_entity: Entity,
+        sink: JsonlSink,
+        excluded_roots: Iterable[Path] = (),
+    ) -> None:
+        self.root = root.expanduser().resolve()
+        self.handler = SessionFileEventHandler(
+            session_id=session_id,
+            session_entity=session_entity,
+            sink=sink,
+            excluded_roots=excluded_roots,
+        )
+        self.observer = Observer()
+
+    def start(self) -> None:
+        self.observer.schedule(self.handler, str(self.root), recursive=True)
+        self.observer.start()
+
+    def stop(self) -> None:
+        self.observer.stop()
+        self.observer.join(timeout=5)