execweave 0.6.0__py3-none-any.whl

execweave/opencode_adapter.py

@@ -0,0 +1,316 @@
+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 = {"chat.message", "tool.execute.before", "tool.execute.after"}
+
+
+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": "opencode_plugin",
+        "evidence_source": "provider_plugin",
+        "provider": "opencode",
+        "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:OpenCode", name="OpenCode")
+
+
+def _common(payload: dict[str, Any]) -> dict[str, Any]:
+    attrs: dict[str, Any] = {}
+    for source, target in (
+        ("sessionID", "opencode_session_id"),
+        ("callID", "opencode_call_id"),
+        ("messageID", "opencode_message_id"),
+        ("agent", "opencode_agent"),
+        ("cwd", "opencode_cwd"),
+    ):
+        value = payload.get(source)
+        if isinstance(value, (str, int, float, bool)) and value != "":
+            attrs[target] = value
+    return attrs
+
+
+def _tool_entity(tool: str) -> dict[str, Any]:
+    return _entity(
+        "tool",
+        f"tool:opencode:{tool}",
+        name=tool,
+        attributes={"provider": "opencode", "native_name": tool},
+    )
+
+
+def _tool_call(payload: dict[str, Any], tool: str) -> dict[str, Any]:
+    session_id = payload.get("sessionID")
+    call_id = payload.get("callID")
+    if not isinstance(session_id, str) or not session_id:
+        raise ValueError("OpenCode tool hook requires sessionID")
+    if not isinstance(call_id, str) or not call_id:
+        raise ValueError("OpenCode tool hook requires callID")
+    attrs = _common(payload)
+    attrs.update({"provider": "opencode", "tool_name": tool, "call_id": call_id})
+    safe_args = payload.get("args")
+    if isinstance(safe_args, dict):
+        attrs["input_keys"] = sorted(str(key) for key in safe_args)
+    return _entity(
+        "tool_call",
+        f"tool-call:opencode:{session_id}:{call_id}",
+        name=tool,
+        attributes=attrs,
+    )
+
+
+def _command_entity(args: dict[str, Any]) -> dict[str, Any] | None:
+    command, truncated = _clean_text(args.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(payload: dict[str, Any], args: dict[str, Any]) -> dict[str, Any] | None:
+    raw = None
+    for key in ("filePath", "file_path", "path"):
+        value = args.get(key)
+        if isinstance(value, str) and value:
+            raw = value
+            break
+    if raw is None:
+        return None
+    candidate = Path(raw).expanduser()
+    if not candidate.is_absolute():
+        cwd = payload.get("cwd")
+        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_plugin": True, "provider": "opencode"},
+    )
+
+
+def _chat_message(payload: dict[str, Any], *, timestamp: str) -> list[dict[str, Any]]:
+    model = payload.get("model")
+    if not isinstance(model, dict):
+        return []
+    provider_id = model.get("providerID")
+    model_id = model.get("modelID")
+    if not isinstance(model_id, str) or not model_id:
+        return []
+    name = f"{provider_id}/{model_id}" if isinstance(provider_id, str) and provider_id else model_id
+    return [
+        _event(
+            timestamp=timestamp,
+            event_type="semantic.opencode.model.observed",
+            relation="USED_MODEL",
+            source=_agent(),
+            target=_entity(
+                "model",
+                f"model:opencode:{name}",
+                name=name,
+                attributes={
+                    "provider": "opencode",
+                    "model_provider_id": provider_id,
+                    "model_id": model_id,
+                },
+            ),
+            attributes=_common(payload),
+        )
+    ]
+
+
+def _before(payload: dict[str, Any], *, timestamp: str) -> list[dict[str, Any]]:
+    tool = payload.get("tool")
+    if not isinstance(tool, str) or not tool:
+        raise ValueError("OpenCode tool.execute.before requires tool")
+    call = _tool_call(payload, tool)
+    common = _common(payload)
+    events = [
+        _event(
+            timestamp=timestamp,
+            event_type="semantic.opencode.tool.requested",
+            relation="REQUESTED_TOOL_CALL",
+            source=_agent(),
+            target=call,
+            attributes=common,
+        ),
+        _event(
+            timestamp=timestamp,
+            event_type="semantic.opencode.tool.selected",
+            relation="USES_TOOL",
+            source=call,
+            target=_tool_entity(tool),
+            attributes=common,
+        ),
+    ]
+    args = payload.get("args")
+    if isinstance(args, dict):
+        if tool == "bash":
+            command = _command_entity(args)
+            if command is not None:
+                events.append(
+                    _event(
+                        timestamp=timestamp,
+                        event_type="semantic.opencode.command.declared",
+                        relation="DECLARED_COMMAND",
+                        source=call,
+                        target=command,
+                        attributes=common,
+                    )
+                )
+        target = _declared_file(payload, args)
+        if target is not None:
+            events.append(
+                _event(
+                    timestamp=timestamp,
+                    event_type="semantic.opencode.file.declared",
+                    relation="DECLARED_TARGET",
+                    source=call,
+                    target=target,
+                    attributes=common,
+                )
+            )
+    return events
+
+
+def _after(payload: dict[str, Any], *, timestamp: str) -> list[dict[str, Any]]:
+    tool = payload.get("tool")
+    if not isinstance(tool, str) or not tool:
+        raise ValueError("OpenCode tool.execute.after requires tool")
+    call = _tool_call(payload, tool)
+    return [
+        _event(
+            timestamp=timestamp,
+            event_type="semantic.opencode.tool.returned",
+            relation="TOOL_CALL_RETURNED",
+            source=call,
+            target=_tool_entity(tool),
+            attributes=_common(payload),
+        )
+    ]
+
+
+def opencode_plugin_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("OpenCode payload requires hook_event_name")
+    if hook_event not in _SUPPORTED_EVENTS:
+        return []
+    observed_at = timestamp or _now()
+    if hook_event == "chat.message":
+        return _chat_message(payload, timestamp=observed_at)
+    if hook_event == "tool.execute.before":
+        return _before(payload, timestamp=observed_at)
+    return _after(payload, timestamp=observed_at)
+
+
+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_plugin_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("OpenCode plugin stdin is empty")
+    try:
+        payload = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"OpenCode plugin stdin is invalid JSON: {exc.msg}") from exc
+    if not isinstance(payload, dict):
+        raise ValueError("OpenCode plugin stdin must be one JSON object")
+    return payload

execweave/opencode_hook_cli.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from .opencode_adapter import (
+    append_semantic_records,
+    opencode_plugin_to_semantic_events,
+    read_plugin_payload,
+)
+
+
+def _default_sidecar(payload: dict) -> Path:
+    cwd = payload.get("cwd")
+    if not isinstance(cwd, str) or not cwd:
+        cwd = str(Path.cwd())
+    session_id = payload.get("sessionID")
+    if not isinstance(session_id, str) or not session_id:
+        raise ValueError("OpenCode payload has no sessionID for sidecar placement")
+    safe = "".join(
+        character if character.isalnum() or character in {"-", "_", "."} else "_"
+        for character in session_id
+    )
+    return Path(cwd) / ".execweave" / "semantic" / "opencode" / f"{safe}.jsonl"
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="execweave-opencode-hook",
+        description="Capture OpenCode plugin telemetry as local ExecWeave semantic events.",
+    )
+    parser.add_argument("--sidecar", type=Path, default=None)
+    parser.add_argument("--strict", action="store_true")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        payload = read_plugin_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, opencode_plugin_to_semantic_events(payload))
+    except (OSError, TimeoutError, ValueError) as exc:
+        print(f"ExecWeave OpenCode hook warning: {exc}", file=sys.stderr)
+        if args.strict:
+            return 1
+    print("{}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

execweave/opencode_plugin_cli.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+_PLUGIN = r'''const safeArgs = (tool, args) => {
+  if (!args || typeof args !== "object") return {}
+  const safe = {}
+  if (tool === "bash" && typeof args.command === "string") {
+    safe.command = args.command
+  }
+  for (const key of ["filePath", "file_path", "path", "cwd", "workdir"]) {
+    if (typeof args[key] === "string") safe[key] = args[key]
+  }
+  return safe
+}
+
+export const ExecWeavePlugin = async ({ directory }) => {
+  const emit = async (payload) => {
+    try {
+      const proc = Bun.spawn(["execweave-opencode-hook"], {
+        stdin: "pipe",
+        stdout: "ignore",
+        stderr: "inherit",
+        env: process.env,
+      })
+      proc.stdin.write(JSON.stringify({ ...payload, cwd: directory }))
+      proc.stdin.end()
+      await proc.exited
+    } catch (error) {
+      console.error("ExecWeave OpenCode plugin warning:", error)
+    }
+  }
+
+  return {
+    "chat.message": async (input) => {
+      await emit({
+        hook_event_name: "chat.message",
+        sessionID: input.sessionID,
+        agent: input.agent,
+        model: input.model,
+        messageID: input.messageID,
+      })
+    },
+    "tool.execute.before": async (input, output) => {
+      await emit({
+        hook_event_name: "tool.execute.before",
+        sessionID: input.sessionID,
+        callID: input.callID,
+        tool: input.tool,
+        args: safeArgs(input.tool, output.args),
+      })
+    },
+    "tool.execute.after": async (input) => {
+      await emit({
+        hook_event_name: "tool.execute.after",
+        sessionID: input.sessionID,
+        callID: input.callID,
+        tool: input.tool,
+        args: safeArgs(input.tool, input.args),
+      })
+    },
+  }
+}
+'''
+
+
+def plugin_text() -> str:
+    return _PLUGIN
+
+
+def install_plugin(root: str | Path, *, force: bool = False) -> Path:
+    project = Path(root).expanduser().resolve()
+    target = project / ".opencode" / "plugins" / "execweave.ts"
+    if target.exists() and target.stat().st_size > 0 and not force:
+        raise FileExistsError(f"OpenCode ExecWeave plugin already exists: {target}")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(plugin_text(), encoding="utf-8", newline="\n")
+    return target
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="execweave-opencode-plugin",
+        description="Install or print the local ExecWeave OpenCode telemetry plugin.",
+    )
+    action = parser.add_mutually_exclusive_group(required=True)
+    action.add_argument("--install", action="store_true")
+    action.add_argument("--print-plugin", action="store_true")
+    parser.add_argument("--root", type=Path, default=Path.cwd())
+    parser.add_argument("--force", action="store_true")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.print_plugin:
+        print(plugin_text(), end="")
+        return 0
+    try:
+        target = install_plugin(args.root, force=args.force)
+    except (OSError, FileExistsError) as exc:
+        parser.error(str(exc))
+    print(target)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

execweave/opencode_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
+
+OpenCodeRecordResult = ProviderRecordResult
+
+
+def record_opencode_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,
+) -> OpenCodeRecordResult:
+    return record_provider_to_viewer(
+        command,
+        provider_name="OpenCode",
+        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-opencode-record",
+        description=(
+            "Record runtime evidence, OpenCode plugin 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("an OpenCode command is required, e.g. execweave-opencode-record --open -- opencode")
+    watch_root = (args.watch_root or Path.cwd()).expanduser().resolve()
+    try:
+        result = record_opencode_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())