execweave 0.8.23__tar.gz → 0.8.24__tar.gz

{execweave-0.8.23 → execweave-0.8.24}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: execweave
-Version: 0.8.23
+Version: 0.8.24
 Summary: Turn AI-agent runtime behavior into a local interactive execution graph.
 Project-URL: Homepage, https://github.com/Irish-kw/ExecWeave
 Project-URL: Repository, https://github.com/Irish-kw/ExecWeave
@@ -369,3 +369,24 @@ Issues and pull requests are welcome. Keep new integrations evidence-aware: docu
 ## License
 
 ExecWeave is distributed under the **PolyForm Noncommercial License 1.0.0**. See [LICENSE](LICENSE) for the full terms.
+## Framework Adapter SDK
+
+ExecWeave includes an optional authoritative adapter SDK for CAMEL Workforce,
+AutoGen AgentChat/Core, and MetaGPT. Adapters emit canonical agent, task,
+message, model, and tool records; they do not infer logical conversations from
+process names or network traffic. Content capture is opt-in and hidden
+reasoning/private reasoning is never captured by the SDK. Transport credentials
+are removed from semantic metadata.
+
+See [the framework adapter guide](docs/framework-adapters.md) for the public
+API, compatibility matrix, live/final parity contract, and official CAMEL,
+AutoGen, and MetaGPT paper references. Current framework versions still require
+the corresponding optional dependency and an authoritative callback or event
+boundary in the application.
+
+Paper context: Li et al., *CAMEL: Communicative Agents for "Mind" Exploration of Large Language Model Society* ([arXiv:2303.17760](https://arxiv.org/abs/2303.17760), 2023); Wu et al., *AutoGen: Enabling Next-Gen LLM Applications via Multi-Agent Conversation* ([arXiv:2308.08155](https://arxiv.org/abs/2308.08155), 2023); Hong et al., *MetaGPT: Meta Programming for a Multi-Agent Collaborative Framework* ([OpenReview, ICLR 2024](https://openreview.net/forum?id=VtmBAGCN7o)).
+
+```python
+from execweave.framework_adapters import AdapterContext, CAMELAdapter
+adapter = CAMELAdapter(AdapterContext.from_environment("camel"))
+```

{execweave-0.8.23 → execweave-0.8.24}/README.md

@@ -309,3 +309,24 @@ Issues and pull requests are welcome. Keep new integrations evidence-aware: docu
 ## License
 
 ExecWeave is distributed under the **PolyForm Noncommercial License 1.0.0**. See [LICENSE](LICENSE) for the full terms.
+## Framework Adapter SDK
+
+ExecWeave includes an optional authoritative adapter SDK for CAMEL Workforce,
+AutoGen AgentChat/Core, and MetaGPT. Adapters emit canonical agent, task,
+message, model, and tool records; they do not infer logical conversations from
+process names or network traffic. Content capture is opt-in and hidden
+reasoning/private reasoning is never captured by the SDK. Transport credentials
+are removed from semantic metadata.
+
+See [the framework adapter guide](docs/framework-adapters.md) for the public
+API, compatibility matrix, live/final parity contract, and official CAMEL,
+AutoGen, and MetaGPT paper references. Current framework versions still require
+the corresponding optional dependency and an authoritative callback or event
+boundary in the application.
+
+Paper context: Li et al., *CAMEL: Communicative Agents for "Mind" Exploration of Large Language Model Society* ([arXiv:2303.17760](https://arxiv.org/abs/2303.17760), 2023); Wu et al., *AutoGen: Enabling Next-Gen LLM Applications via Multi-Agent Conversation* ([arXiv:2308.08155](https://arxiv.org/abs/2308.08155), 2023); Hong et al., *MetaGPT: Meta Programming for a Multi-Agent Collaborative Framework* ([OpenReview, ICLR 2024](https://openreview.net/forum?id=VtmBAGCN7o)).
+
+```python
+from execweave.framework_adapters import AdapterContext, CAMELAdapter
+adapter = CAMELAdapter(AdapterContext.from_environment("camel"))
+```

{execweave-0.8.23 → execweave-0.8.24}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "execweave"
-# ExecWeave v0.8.23 release metadata
-version = "0.8.23"
+# ExecWeave v0.8.24 release metadata
+version = "0.8.24"
 description = "Turn AI-agent runtime behavior into a local interactive execution graph."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -69,6 +69,11 @@ Repository = "https://github.com/Irish-kw/ExecWeave"
 Documentation = "https://github.com/Irish-kw/ExecWeave#documentation"
 Issues = "https://github.com/Irish-kw/ExecWeave/issues"
 
+[project.entry-points."execweave.framework_adapters"]
+camel = "execweave.framework_adapters.camel:CAMELAdapter"
+autogen = "execweave.framework_adapters.autogen:AutoGenAdapter"
+metagpt = "execweave.framework_adapters.metagpt:MetaGPTAdapter"
+
 [project.scripts]
 execweave = "execweave.entry:main"
 execweave-top = "execweave.top_cli:main"

{execweave-0.8.23 → execweave-0.8.24}/src/execweave/__init__.py

@@ -1,3 +1,3 @@
 """ExecWeave runtime graph package."""
 
-__version__ = "0.8.23"
+__version__ = "0.8.24"

{execweave-0.8.23 → execweave-0.8.24}/src/execweave/_conversation_records_core.py

@@ -4,6 +4,7 @@ import json
 import re
 from pathlib import Path
 from typing import Any
+from .content_store import _filesystem_path
 
 from .agent_topology import (
     COMPLETENESS_ROUTING_ONLY,
@@ -108,8 +109,9 @@ def _provider(source: dict[str, Any] | None, content_kind: str) -> str:
 
 def _run_local_path(root: Path, relative: str) -> Path | None:
     try:
-        candidate = (root / relative).resolve(strict=False)
-        candidate.relative_to(root)
+        root_fs = _filesystem_path(root)
+        candidate = (root_fs / relative).resolve(strict=False)
+        candidate.relative_to(root_fs)
     except (OSError, RuntimeError, ValueError):
         return None
     return candidate if candidate.is_file() else None

{execweave-0.8.23 → execweave-0.8.24}/src/execweave/collector.py

@@ -20,6 +20,11 @@ from .auto_specialized import (
     run_post_command_specialized_probe,
 )
 from .command import resolve_launch_command
+from .cursor_lifecycle import (
+    is_cursor_invocation,
+    process_baseline,
+    run_cursor_handoff,
+)
 from .filesystem import FileWatcher
 from .schema import Entity, RuntimeEvent
 from .sink import JsonlSink
@@ -137,6 +142,8 @@ class RuntimeCollector:
         self._network_sample_errors = 0
         self._network_access_denied = 0
         self._collector_children_baseline: dict[int, float] | None = None
+        self._preserved_processes: set[tuple[int, float]] = set()
+        self._cursor_handoff_info: dict[str, object] = {}
 
     def _filesystem_excluded_roots(self) -> list[Path]:
         """Return ExecWeave-owned paths that must never become workload evidence.
@@ -165,6 +172,12 @@ class RuntimeCollector:
             raise ValueError("command must not be empty")
 
         launch_command = resolve_launch_command(command)
+        cursor_invocation = os.name == "nt" and is_cursor_invocation(command)
+        cursor_baseline = process_baseline(launch_command[0]) if cursor_invocation else set()
+        self._preserved_processes = set()
+        self._cursor_handoff_info = {
+            "cursor_lifecycle_handoff": "launcher" if cursor_invocation else "not_applicable",
+        }
         agent_name = infer_agent_name(command)
         agent = Entity(type="agent", id=f"agent:{agent_name}", name=agent_name)
         session = Entity(
@@ -206,6 +219,7 @@ class RuntimeCollector:
         process: subprocess.Popen[bytes] | None = None
         owned: list[psutil.Process] = []
         return_code = 1
+        cursor_root_snapshot: ProcessSnapshot | None = None
         interrupted = False
         collector_error_type: str | None = None
         workload_terminated_due_to_collector_error = False
@@ -236,6 +250,7 @@ class RuntimeCollector:
                     snapshot = _safe_process_snapshot(root)
                     if snapshot is not None:
                         self._record_process_start(snapshot, parent=session, relation="LAUNCHED")
+                        cursor_root_snapshot = snapshot if cursor_invocation else None
 
                     with auto_specialized_probe(command, admission=live_probe_admission):
                         while process.poll() is None:
@@ -245,6 +260,14 @@ class RuntimeCollector:
                         self._sample_process_tree(root)
                         self._mark_disappeared_processes(set())
                     return_code = int(process.returncode or 0)
+
+                    if cursor_invocation and cursor_root_snapshot is not None:
+                        run_cursor_handoff(
+                            self,
+                            root_snapshot=cursor_root_snapshot,
+                            executable=launch_command[0],
+                            baseline=cursor_baseline,
+                        )
             except KeyboardInterrupt:
                 interrupted = True
                 return_code = 130
@@ -300,6 +323,7 @@ class RuntimeCollector:
                         "network_sample_errors": self._network_sample_errors,
                         "network_access_denied": self._network_access_denied,
                         "execweave_version": __version__,
+                        **self._cursor_handoff_info,
                     },
                 )
             )
@@ -394,6 +418,8 @@ class RuntimeCollector:
         def add_with_descendants(candidate: psutil.Process) -> None:
             if not self._process_is_live(candidate):
                 return
+            if (candidate.pid, candidate.create_time()) in self._preserved_processes:
+                return
             owned[candidate.pid] = candidate
             try:
                 descendants = candidate.children(recursive=True)
@@ -401,6 +427,8 @@ class RuntimeCollector:
                 descendants = []
             for child in descendants:
                 if self._process_is_live(child):
+                    if (child.pid, child.create_time()) in self._preserved_processes:
+                        continue
                     owned[child.pid] = child
 
         if process.poll() is None:

{execweave-0.8.23 → execweave-0.8.24}/src/execweave/content_store.py

@@ -13,6 +13,20 @@ _HASH_ALGORITHM = "sha256"
 _COPY_CHUNK_BYTES = 1024 * 1024
 
 
+def _filesystem_path(path: Path) -> Path:
+    """Use Win32 extended paths for content stores beyond ``MAX_PATH``."""
+    if os.name != "nt":
+        return path
+    value = os.fspath(path)
+    if value.startswith("\\\\?\\"):
+        return path
+    if value.startswith("\\\\"):
+        return Path("\\\\?\\UNC\\" + value[2:])
+    if os.path.isabs(value):
+        return Path("\\\\?\\" + value)
+    return path
+
+
 @dataclass(frozen=True)
 class ContentReference:
     """Reference to one complete locally stored observation.
@@ -118,9 +132,12 @@ class FullFidelityContentStore:
         if not content_kind:
             raise ValueError("content_kind must not be empty")
         source_path = Path(source).expanduser().resolve()
-        if not source_path.is_file():
+        source_fs = _filesystem_path(source_path)
+        if not source_fs.is_file():
             raise FileNotFoundError(source_path)
-        destination_dir = self.run_root / _CONTENT_DIR / _HASH_ALGORITHM
+        destination_dir = _filesystem_path(
+            self.run_root / _CONTENT_DIR / _HASH_ALGORITHM
+        )
         destination_dir.mkdir(parents=True, exist_ok=True)
         if os.name != "nt":
             try:
@@ -128,9 +145,9 @@ class FullFidelityContentStore:
             except OSError:
                 pass
 
-        before = source_path.stat()
+        before = source_fs.stat()
         fd, temp_name = tempfile.mkstemp(prefix=".execweave-content-", dir=destination_dir)
-        temp_path = Path(temp_name)
+        temp_path = _filesystem_path(Path(temp_name))
         digest = hashlib.sha256()
         size = 0
         try:
@@ -139,7 +156,7 @@ class FullFidelityContentStore:
                     os.fchmod(fd, 0o600)
                 except OSError:
                     pass
-            with source_path.open("rb") as source_handle, os.fdopen(
+            with source_fs.open("rb") as source_handle, os.fdopen(
                 fd, "wb", closefd=True
             ) as destination_handle:
                 while True:
@@ -152,7 +169,7 @@ class FullFidelityContentStore:
                 destination_handle.flush()
                 os.fsync(destination_handle.fileno())
 
-            after = source_path.stat()
+            after = source_fs.stat()
             before_signature = (before.st_size, before.st_mtime_ns)
             after_signature = (after.st_size, after.st_mtime_ns)
             if before_signature != after_signature or size != after.st_size:
@@ -162,14 +179,18 @@ class FullFidelityContentStore:
             suffix = _suffix_for_media_type(media_type)
             relative = Path(_CONTENT_DIR) / _HASH_ALGORITHM / f"{digest_hex}{suffix}"
             destination = self.run_root / relative
-            if destination.exists():
-                if destination.stat().st_size != size or self._file_sha256(destination) != digest_hex:
+            destination_fs = _filesystem_path(destination)
+            if destination_fs.exists():
+                if (
+                    destination_fs.stat().st_size != size
+                    or self._file_sha256(destination_fs) != digest_hex
+                ):
                     raise RuntimeError(f"content hash collision at {destination}")
             else:
-                temp_path.replace(destination)
+                temp_path.replace(destination_fs)
             if os.name != "nt":
                 try:
-                    destination.chmod(0o600)
+                    destination_fs.chmod(0o600)
                 except OSError:
                     pass
             return ContentReference(
@@ -195,19 +216,22 @@ class FullFidelityContentStore:
         return digest.hexdigest()
 
     def _write_once(self, destination: Path, payload: bytes) -> None:
-        destination.parent.mkdir(parents=True, exist_ok=True)
+        destination_fs = _filesystem_path(destination)
+        destination_fs.parent.mkdir(parents=True, exist_ok=True)
         if os.name != "nt":
             try:
-                destination.parent.chmod(0o700)
+                destination_fs.parent.chmod(0o700)
             except OSError:
                 pass
-        if destination.exists():
-            if destination.read_bytes() != payload:
+        if destination_fs.exists():
+            if destination_fs.read_bytes() != payload:
                 raise RuntimeError(f"content hash collision at {destination}")
             return
 
-        fd, temp_name = tempfile.mkstemp(prefix=".execweave-content-", dir=destination.parent)
-        temp_path = Path(temp_name)
+        fd, temp_name = tempfile.mkstemp(
+            prefix=".execweave-content-", dir=destination_fs.parent
+        )
+        temp_path = _filesystem_path(Path(temp_name))
         try:
             if os.name != "nt":
                 try:
@@ -219,15 +243,15 @@ class FullFidelityContentStore:
                 handle.flush()
                 os.fsync(handle.fileno())
             try:
-                temp_path.replace(destination)
+                temp_path.replace(destination_fs)
             except OSError:
-                if destination.exists() and destination.read_bytes() == payload:
+                if destination_fs.exists() and destination_fs.read_bytes() == payload:
                     temp_path.unlink(missing_ok=True)
                 else:
                     raise
             if os.name != "nt":
                 try:
-                    destination.chmod(0o600)
+                    destination_fs.chmod(0o600)
                 except OSError:
                     pass
         finally:

execweave-0.8.24/src/execweave/cursor_lifecycle.py

@@ -0,0 +1,159 @@
+"""Attribution-safe Cursor GUI launcher hand-off helpers."""
+
+from __future__ import annotations
+
+import os
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Iterable
+
+import psutil
+
+
+@dataclass(frozen=True)
+class CursorHandoff:
+    status: str
+    snapshot: Any | None = None
+    process: psutil.Process | None = None
+
+
+def is_cursor_invocation(command: Iterable[str]) -> bool:
+    values = list(command)
+    if not values:
+        return False
+    name = Path(values[0]).name.lower()
+    for suffix in (".exe", ".cmd", ".bat", ".ps1"):
+        if name.endswith(suffix):
+            name = name[: -len(suffix)]
+            break
+    return name == "cursor"
+
+
+def normalized_executable(value: str | None) -> str | None:
+    if not value:
+        return None
+    try:
+        return os.path.normcase(str(Path(value).expanduser().resolve(strict=False)))
+    except (OSError, RuntimeError, ValueError):
+        return os.path.normcase(str(value))
+
+
+def process_identity(snapshot: Any) -> tuple[int, float]:
+    return snapshot.pid, snapshot.create_time
+
+
+def process_baseline(executable: str | None) -> set[tuple[int, float]]:
+    """Return exact PID/create-time identities already using this executable."""
+    target = normalized_executable(executable)
+    if target is None:
+        return set()
+    identities: set[tuple[int, float]] = set()
+    try:
+        processes = psutil.process_iter(["pid", "create_time", "exe"])
+    except (OSError, RuntimeError):
+        return identities
+    for process in processes:
+        try:
+            info = process.info
+            if normalized_executable(info.get("exe")) == target:
+                create_time = info.get("create_time")
+                if isinstance(create_time, (int, float)):
+                    identities.add((int(info["pid"]), float(create_time)))
+        except (KeyError, OSError, psutil.Error):
+            continue
+    return identities
+
+
+def _descends_from(snapshot: Any, root_pid: int, snapshots: dict[int, Any]) -> bool:
+    current = snapshot
+    visited: set[int] = set()
+    while current.ppid > 0 and current.ppid not in visited:
+        if current.ppid == root_pid:
+            return True
+        visited.add(current.ppid)
+        parent = snapshots.get(current.ppid)
+        if parent is None:
+            return False
+        current = parent
+    return False
+
+
+def select_handoff_candidate(
+    snapshots: Iterable[Any],
+    *,
+    root: Any,
+    executable: str | None,
+    baseline: set[tuple[int, float]],
+) -> CursorHandoff:
+    """Select exactly one newly-created descendant of the launcher.
+
+    The function intentionally abstains when process ancestry or identity is
+    ambiguous. It never searches by the string ``Cursor.exe`` alone.
+    """
+    target = normalized_executable(executable)
+    if target is None:
+        return CursorHandoff("unattributed_no_executable")
+    snapshot_map = {snapshot.pid: snapshot for snapshot in snapshots}
+    candidates = []
+    for snapshot in snapshot_map.values():
+        identity = process_identity(snapshot)
+        if identity == process_identity(root) or identity in baseline:
+            continue
+        if normalized_executable(snapshot.exe) != target:
+            continue
+        if snapshot.create_time < root.create_time:
+            continue
+        if not _descends_from(snapshot, root.pid, snapshot_map):
+            continue
+        try:
+            process = psutil.Process(snapshot.pid)
+            if process.is_running() and process.status() != psutil.STATUS_ZOMBIE:
+                candidates.append((snapshot, process))
+        except psutil.Error:
+            continue
+    if not candidates:
+        return CursorHandoff("no_attributed_candidate")
+    if len(candidates) != 1:
+        return CursorHandoff("ambiguous_candidates")
+    snapshot, process = candidates[0]
+    return CursorHandoff("handoff", snapshot=snapshot, process=process)
+
+
+def run_cursor_handoff(
+    collector: Any,
+    *,
+    root_snapshot: Any,
+    executable: str,
+    baseline: set[tuple[int, float]],
+) -> None:
+    """Keep Live attached to one identity-safe GUI successor until it exits."""
+    snapshots = [
+        *collector._seen_processes.values(),
+        *collector._discovered_processes.values(),
+        root_snapshot,
+    ]
+    handoff = select_handoff_candidate(
+        snapshots,
+        root=root_snapshot,
+        executable=executable,
+        baseline=baseline,
+    )
+    collector._cursor_handoff_info["cursor_handoff_status"] = handoff.status
+    if handoff.status != "handoff" or handoff.process is None or handoff.snapshot is None:
+        return
+
+    collector._preserved_processes.add((handoff.snapshot.pid, handoff.snapshot.create_time))
+    collector._cursor_handoff_info.update(
+        {
+            "cursor_handoff_pid": handoff.snapshot.pid,
+            "cursor_handoff_create_time": handoff.snapshot.create_time,
+            "cursor_handoff_status": "active",
+        }
+    )
+    while collector._process_is_live(handoff.process):
+        collector._sample_process_tree(handoff.process)
+        time.sleep(collector.poll_interval)
+    collector._sample_process_tree(handoff.process)
+    collector._mark_disappeared_processes(set())
+    collector._cursor_handoff_info["cursor_handoff_status"] = "completed"

execweave-0.8.24/src/execweave/framework_adapters/__init__.py

@@ -0,0 +1,34 @@
+"""Stable public API for third-party framework semantic adapters."""
+
+from .autogen import AutoGenAdapter
+from .base import (
+    CANONICAL_EVENT_TYPES,
+    AdapterCapabilities,
+    AdapterContext,
+    AgentRecord,
+    CaptureMode,
+    ContentCapturePolicy,
+    ContentWriter,
+    EntityRef,
+    FrameworkAdapter,
+    FrameworkCompatibility,
+    MessageRecord,
+    ModelCallRecord,
+    ProcessRef,
+    SemanticWriter,
+    TaskRecord,
+    ToolCallRecord,
+    stable_id,
+)
+from .camel import CAMELAdapter
+from .metagpt import MetaGPTAdapter
+from .registry import AdapterDescriptor, FrameworkAdapterRegistry, default_registry
+
+__all__ = [
+    "AdapterCapabilities", "AdapterContext", "AdapterDescriptor", "AgentRecord",
+    "AutoGenAdapter", "CAMELAdapter", "CANONICAL_EVENT_TYPES", "CaptureMode",
+    "ContentCapturePolicy", "ContentWriter", "EntityRef", "FrameworkAdapter",
+    "FrameworkAdapterRegistry", "FrameworkCompatibility", "MessageRecord",
+    "MetaGPTAdapter", "ModelCallRecord", "ProcessRef", "SemanticWriter",
+    "TaskRecord", "ToolCallRecord", "default_registry", "stable_id",
+]