eda-bridge-runtime 0.1.0a5__py3-none-any.whl

eda_bridge_runtime/__init__.py

@@ -0,0 +1,33 @@
+"""Agent-neutral execution runtime for EDA bridges."""
+
+from ._version import __version__
+from .adapter import Adapter, AdapterContext, AdapterResult
+from .connections import ConnectionRegistry, ConnectionSpec, discover_connection_origin
+from .context import EDAContext, capability_digest, stable_origin_id
+from .jobs import JobStore
+from .ledger import ExecutionLedger
+from .protocol import ActorIdentity, RequestEnvelope, ResponseEnvelope, project_run
+from .runtime import Runtime
+from .supervisor import run_job_worker, spawn_detached_worker
+
+__all__ = [
+    "__version__",
+    "ActorIdentity",
+    "Adapter",
+    "AdapterContext",
+    "AdapterResult",
+    "ConnectionRegistry",
+    "ConnectionSpec",
+    "discover_connection_origin",
+    "EDAContext",
+    "capability_digest",
+    "ExecutionLedger",
+    "JobStore",
+    "RequestEnvelope",
+    "ResponseEnvelope",
+    "Runtime",
+    "project_run",
+    "run_job_worker",
+    "spawn_detached_worker",
+    "stable_origin_id",
+]

eda_bridge_runtime/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0a5"

eda_bridge_runtime/adapter.py

@@ -0,0 +1,36 @@
+"""Minimal adapter SDK. Vendor semantics stay outside the runtime core."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+from .protocol import RequestEnvelope
+
+
+@dataclass(frozen=True)
+class AdapterResult:
+    status: str
+    result: dict[str, Any] = field(default_factory=dict)
+    artifacts: tuple[dict[str, Any], ...] = ()
+
+
+@dataclass(frozen=True)
+class AdapterContext:
+    emit: Callable[[str, dict[str, Any]], None]
+    fencing_token: int | None = None
+
+
+class Adapter(ABC):
+    name: str
+    version: str
+
+    @abstractmethod
+    def capabilities(self, target: dict[str, Any] | None = None) -> dict[str, Any]:
+        """Return typed operations and explicit escape lanes for an optional target."""
+
+    @abstractmethod
+    def execute(self, request: RequestEnvelope, context: AdapterContext) -> AdapterResult:
+        """Execute one idempotent request and return normalized evidence."""

eda_bridge_runtime/agent_audit.py

@@ -0,0 +1,152 @@
+"""Agent-host audit events captured outside the model context."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+from .ledger import ExecutionLedger
+from .protocol import RUN_VIEW_PROTOCOL, ActorIdentity
+
+AGENT_AUDIT_PROTOCOL = "eda-runtime.agent-audit/v1"
+_RUNTIME_TOOL = re.compile(r"^mcp__(?P<server>.+)__(?P<tool>.+)$")
+_TOOL_NAMES = {
+    "eda_capabilities": "eda.capabilities",
+    "eda_submit": "eda.submit",
+    "eda_job_status": "eda.job.status",
+    "eda_job_events": "eda.job.events",
+    "eda_connections_list": "eda.connections.list",
+    "eda_context_resolve": "eda.context.resolve",
+    "eda.capabilities": "eda.capabilities",
+    "eda.submit": "eda.submit",
+    "eda.job.status": "eda.job.status",
+    "eda.job.events": "eda.job.events",
+    "eda.connections.list": "eda.connections.list",
+    "eda.context.resolve": "eda.context.resolve",
+}
+
+
+def default_agent_audit_path() -> Path:
+    root = Path(os.environ.get("EDA_RUNTIME_HOME", Path.home() / ".eda-bridge-runtime"))
+    return root / "agent-audit.sqlite3"
+
+
+def record_codex_hook(
+    event: Mapping[str, Any],
+    *,
+    phase: str,
+    database: str | Path | None = None,
+) -> bool:
+    """Record one Codex lifecycle fact without changing the pending tool call."""
+    if phase not in {"pre", "post"}:
+        raise ValueError(f"unsupported hook phase: {phase}")
+    tool_name = str(event.get("tool_name") or "")
+    match = _RUNTIME_TOOL.fullmatch(tool_name)
+    if match is None:
+        return False
+    server_name = match.group("server").lower().replace("-", "_")
+    native_tool_name = match.group("tool")
+    if server_name != "eda_bridge_runtime" or native_tool_name not in _TOOL_NAMES:
+        return False
+    tool_call_id = str(event.get("tool_use_id") or "").strip()
+    session_id = str(event.get("session_id") or "").strip()
+    if not tool_call_id or not session_id:
+        return False
+    tool_input = event.get("tool_input")
+    tool_input = tool_input if isinstance(tool_input, Mapping) else {}
+    purpose = str(tool_input.get("purpose") or "unspecified EDA operation")[:240]
+    fingerprint = _fingerprint(tool_name, tool_input)
+    actor = ActorIdentity.detect(
+        observed={
+            key: value
+            for key, value in {
+                "agent_family": "codex",
+                "model": event.get("model"),
+                "session_id": session_id,
+                "turn_id": event.get("turn_id"),
+                "tool_call_id": tool_call_id,
+                "permission_mode": event.get("permission_mode"),
+            }.items()
+            if value
+        },
+        inferred={"harness": "mcp"},
+    )
+    run_id = _audit_run_id(tool_call_id)
+    request_id = str(event.get("turn_id") or session_id)
+    payload: dict[str, Any] = {
+        "protocol": AGENT_AUDIT_PROTOCOL,
+        "actor": actor.to_dict(),
+        "tool": _TOOL_NAMES[native_tool_name],
+        "purpose": purpose,
+        "input_sha256": fingerprint,
+    }
+    event_type = "agent.tool.requested"
+    if phase == "post":
+        event_type = "agent.tool.completed"
+        payload["execution"] = _execution_reference(event.get("tool_response"))
+    with ExecutionLedger(database or default_agent_audit_path()) as ledger:
+        ledger.append(
+            run_id=run_id,
+            request_id=request_id,
+            event_type=event_type,
+            source="codex-hook",
+            payload=payload,
+        )
+        if phase == "post":
+            ledger.finalize(run_id)
+    return True
+
+
+def audit_events(database: str | Path | None = None, *, limit: int = 20) -> list[dict[str, Any]]:
+    with ExecutionLedger(database or default_agent_audit_path()) as ledger:
+        events = ledger.events()
+    return events[-max(1, min(limit, 1000)) :]
+
+
+def _audit_run_id(tool_call_id: str) -> str:
+    digest = hashlib.sha256(tool_call_id.encode("utf-8")).hexdigest()[:32]
+    return f"agent_{digest}"
+
+
+def _fingerprint(tool_name: str, tool_input: Mapping[str, Any]) -> str:
+    material = {"tool_name": tool_name, "tool_input": tool_input}
+    canonical = json.dumps(material, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()
+
+
+def _execution_reference(value: Any) -> dict[str, Any]:
+    run = _find_run_view(value)
+    if run is None:
+        return {"linked": False}
+    return {
+        "linked": True,
+        "run_id": str(run.get("run_id") or "") or None,
+        "request_id": str(run.get("request_id") or "") or None,
+        "job_id": str(run.get("job_id") or "") or None,
+        "state": str(run.get("state") or "unknown"),
+        "terminal": bool(run.get("terminal", False)),
+    }
+
+
+def _find_run_view(value: Any, *, depth: int = 0) -> Mapping[str, Any] | None:
+    if depth > 8:
+        return None
+    if isinstance(value, Mapping):
+        if value.get("protocol") == RUN_VIEW_PROTOCOL:
+            return value
+        run = value.get("run")
+        if isinstance(run, Mapping) and run.get("protocol") == RUN_VIEW_PROTOCOL:
+            return run
+        for item in value.values():
+            if found := _find_run_view(item, depth=depth + 1):
+                return found
+    elif isinstance(value, list):
+        for item in value:
+            if found := _find_run_view(item, depth=depth + 1):
+                return found
+    return None

eda_bridge_runtime/artifacts.py

@@ -0,0 +1,43 @@
+"""Content-addressed artifact evidence."""
+
+from __future__ import annotations
+
+import hashlib
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Artifact:
+    logical_name: str
+    path: str
+    sha256: str
+    size: int
+    media_type: str = "application/octet-stream"
+    retention_days: int | None = None
+
+    @classmethod
+    def from_path(
+        cls,
+        path: str | Path,
+        *,
+        logical_name: str | None = None,
+        media_type: str = "application/octet-stream",
+        retention_days: int | None = None,
+    ) -> Artifact:
+        source = Path(path)
+        digest = hashlib.sha256()
+        with source.open("rb") as stream:
+            for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+                digest.update(chunk)
+        return cls(
+            logical_name or source.name,
+            str(source),
+            digest.hexdigest(),
+            source.stat().st_size,
+            media_type,
+            retention_days,
+        )
+
+    def to_dict(self) -> dict[str, str | int | None]:
+        return asdict(self)

eda_bridge_runtime/cli.py

@@ -0,0 +1,154 @@
+"""Small operational CLI; EDA-specific commands are supplied by adapters."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from ._version import __version__
+from .connections import ConnectionRegistry, ConnectionSpec, discover_connection_origin
+from .context import EDAContext
+from .ledger import ExecutionLedger
+from .protocol import ActorIdentity, RuntimeFacts
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="eda-runtime")
+    parser.add_argument("--version", action="version", version=__version__)
+    sub = parser.add_subparsers(dest="command", required=True)
+    sub.add_parser("doctor")
+    context = sub.add_parser("context")
+    context_sub = context.add_subparsers(dest="context_command", required=True)
+    decode = context_sub.add_parser("decode")
+    decode.add_argument("token")
+    ledger = sub.add_parser("ledger")
+    ledger_sub = ledger.add_subparsers(dest="ledger_command", required=True)
+    verify = ledger_sub.add_parser("verify")
+    verify.add_argument("database", type=Path)
+    verify.add_argument("run_id")
+    export = ledger_sub.add_parser("export")
+    export.add_argument("database", type=Path)
+    export.add_argument("destination", type=Path)
+    connection = sub.add_parser("connection")
+    connection_sub = connection.add_subparsers(dest="connection_command", required=True)
+    for action in ("list", "set", "remove"):
+        item = connection_sub.add_parser(action)
+        item.add_argument("--registry", type=Path)
+        if action in {"set", "remove"}:
+            item.add_argument("connection_id")
+        if action == "set":
+            item.add_argument("--eda", required=True)
+            item.add_argument("--kind", choices=("local", "ssh"), required=True)
+            item.add_argument("--host")
+            item.add_argument("--origin-id")
+            item.add_argument("--no-origin-probe", action="store_true")
+            item.add_argument("--ssh-option", action="append", default=[])
+            item.add_argument("--timeout-seconds", type=float, default=30)
+            item.add_argument("launch_command", nargs=argparse.REMAINDER)
+    mcp = sub.add_parser("mcp")
+    mcp_sub = mcp.add_subparsers(dest="mcp_command", required=True)
+    mcp_serve = mcp_sub.add_parser("serve")
+    mcp_serve.add_argument("--registry", type=Path)
+    hook = sub.add_parser("hook")
+    hook_sub = hook.add_subparsers(dest="hook_command", required=True)
+    for phase in ("codex-pre-tool-use", "codex-post-tool-use"):
+        item = hook_sub.add_parser(phase)
+        item.add_argument("--database", type=Path)
+    audit = sub.add_parser("audit")
+    audit_sub = audit.add_subparsers(dest="audit_command", required=True)
+    audit_list = audit_sub.add_parser("list")
+    audit_list.add_argument("--database", type=Path)
+    audit_list.add_argument("--limit", type=int, default=20)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    if args.command == "doctor":
+        print(
+            json.dumps(
+                {
+                    "status": "ok",
+                    "runtime": RuntimeFacts(__version__).to_dict(),
+                    "actor": ActorIdentity.detect().to_dict(),
+                    "protocols": {"request": 1, "context": [1, 2], "handshake": 1},
+                },
+                indent=2,
+            )
+        )
+        return 0
+    if args.command == "context" and args.context_command == "decode":
+        print(json.dumps(EDAContext.decode(args.token).__dict__, indent=2))
+        return 0
+    if args.command == "connection":
+        registry = ConnectionRegistry(args.registry)
+        if args.connection_command == "list":
+            print(
+                json.dumps(
+                    {
+                        "status": "ready",
+                        "connections": [item.to_dict() for item in registry.list()],
+                    },
+                    indent=2,
+                )
+            )
+            return 0
+        if args.connection_command == "remove":
+            removed = registry.remove(args.connection_id)
+            print(json.dumps({"status": "removed" if removed else "not_found"}))
+            return 0 if removed else 1
+        launch_command = list(args.launch_command)
+        if launch_command and launch_command[0] == "--":
+            launch_command.pop(0)
+        spec = ConnectionSpec(
+            connection_id=args.connection_id,
+            eda=args.eda,
+            kind=args.kind,
+            command=tuple(launch_command),
+            host=args.host,
+            ssh_options=tuple(args.ssh_option),
+            timeout_seconds=args.timeout_seconds,
+            origin_id=args.origin_id,
+        )
+        if not spec.origin_id and not args.no_origin_probe:
+            spec = discover_connection_origin(spec)
+        registry.upsert(spec)
+        print(json.dumps({"status": "ready", "connection": spec.to_dict()}, indent=2))
+        return 0
+    if args.command == "mcp" and args.mcp_command == "serve":
+        from .mcp_server import serve_mcp
+
+        serve_mcp(registry=ConnectionRegistry(args.registry))
+        return 0
+    if args.command == "hook":
+        from .agent_audit import record_codex_hook
+
+        try:
+            event = json.load(sys.stdin)
+            phase = "pre" if args.hook_command == "codex-pre-tool-use" else "post"
+            record_codex_hook(event, phase=phase, database=args.database)
+        except Exception:
+            # Audit is fail-open: telemetry must never alter or block an EDA call.
+            return 0
+        return 0
+    if args.command == "audit" and args.audit_command == "list":
+        from .agent_audit import audit_events
+
+        print(json.dumps({"events": audit_events(args.database, limit=args.limit)}, indent=2))
+        return 0
+    if args.command == "ledger":
+        with ExecutionLedger(args.database) as ledger:
+            if args.ledger_command == "verify":
+                valid = ledger.verify(args.run_id)
+                print(json.dumps({"run_id": args.run_id, "valid": valid}))
+                return 0 if valid else 1
+            ledger.export_ndjson(args.destination)
+            print(json.dumps({"status": "ok", "destination": str(args.destination)}))
+            return 0
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

eda_bridge_runtime/connections.py

@@ -0,0 +1,192 @@
+"""Deterministic local and SSH adapter connection registry."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import tempfile
+from dataclasses import asdict, dataclass, replace
+from pathlib import Path
+from typing import Any
+
+from .protocol import RequestEnvelope
+from .transport import PersistentStdioTransport, SSHStdioTransport, Transport
+
+_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$")
+
+
+def runtime_home() -> Path:
+    return Path(os.environ.get("EDA_RUNTIME_HOME", Path.home() / ".eda-bridge-runtime"))
+
+
+def default_connections_path() -> Path:
+    return runtime_home() / "connections.json"
+
+
+@dataclass(frozen=True)
+class ConnectionSpec:
+    connection_id: str
+    eda: str
+    kind: str
+    command: tuple[str, ...]
+    host: str | None = None
+    ssh_options: tuple[str, ...] = ()
+    timeout_seconds: float = 30
+    origin_id: str | None = None
+
+    def __post_init__(self) -> None:
+        if not _ID.fullmatch(self.connection_id):
+            raise ValueError("connection_id must be 1..64 safe identifier characters")
+        if not self.eda.strip() or not self.command:
+            raise ValueError("eda and command are required")
+        if self.kind not in {"local", "ssh"}:
+            raise ValueError("connection kind must be local or ssh")
+        if self.kind == "ssh" and not self.host:
+            raise ValueError("SSH connections require host")
+        if self.kind == "local" and self.host:
+            raise ValueError("local connections must not define host")
+        if self.timeout_seconds <= 0:
+            raise ValueError("timeout_seconds must be positive")
+        if self.origin_id and not _ID.fullmatch(self.origin_id):
+            raise ValueError("origin_id must be 1..64 safe identifier characters")
+
+    def to_dict(self) -> dict[str, Any]:
+        value = asdict(self)
+        value["command"] = list(self.command)
+        value["ssh_options"] = list(self.ssh_options)
+        return value
+
+    @classmethod
+    def from_dict(cls, value: dict[str, Any]) -> ConnectionSpec:
+        data = dict(value)
+        data["command"] = tuple(data.get("command", ()))
+        data["ssh_options"] = tuple(data.get("ssh_options", ()))
+        return cls(**data)
+
+    def open(self) -> Transport:
+        if self.kind == "local":
+            return PersistentStdioTransport(self.command, timeout_seconds=self.timeout_seconds)
+        return SSHStdioTransport(
+            str(self.host),
+            self.command,
+            ssh_options=self.ssh_options,
+            timeout_seconds=self.timeout_seconds,
+        )
+
+
+def discover_connection_origin(
+    spec: ConnectionSpec, *, transport: Transport | None = None
+) -> ConnectionSpec:
+    """Read one adapter identity during connection setup and bind its stable origin."""
+
+    owned = transport is None
+    selected = transport or spec.open()
+    try:
+        response = selected.request(
+            RequestEnvelope(
+                purpose="Bind one registered EDA connection to its stable origin",
+                target={"eda": spec.eda, "connection_id": spec.connection_id},
+                operation="runtime.capabilities",
+                payload={"mutating": False},
+            )
+        )
+    finally:
+        if owned:
+            selected.close()
+    data = response.result.get("data") if isinstance(response.result, dict) else None
+    capabilities = data.get("capabilities") if isinstance(data, dict) else None
+    origin_id = str((capabilities or {}).get("origin_id") or "")
+    if response.status != "passed" or not _ID.fullmatch(origin_id):
+        raise ValueError("EDA adapter did not return a valid stable origin_id")
+    return replace(spec, origin_id=origin_id)
+
+
+class ConnectionRegistry:
+    def __init__(self, path: str | Path | None = None):
+        self.path = Path(path) if path else default_connections_path()
+
+    def list(self) -> list[ConnectionSpec]:
+        if not self.path.is_file():
+            return []
+        data = json.loads(self.path.read_text(encoding="utf-8"))
+        if data.get("schema_version") != 1 or not isinstance(data.get("connections"), list):
+            raise ValueError(f"unsupported connection registry: {self.path}")
+        return sorted(
+            (ConnectionSpec.from_dict(item) for item in data["connections"]),
+            key=lambda item: item.connection_id,
+        )
+
+    def upsert(self, spec: ConnectionSpec) -> ConnectionSpec:
+        values = {item.connection_id: item for item in self.list()}
+        values[spec.connection_id] = spec
+        self._write(list(values.values()))
+        return spec
+
+    def remove(self, connection_id: str) -> bool:
+        values = {item.connection_id: item for item in self.list()}
+        removed = values.pop(connection_id, None) is not None
+        if removed:
+            self._write(list(values.values()))
+        return removed
+
+    def resolve(
+        self,
+        *,
+        connection_id: str | None = None,
+        eda: str | None = None,
+        origin_id: str | None = None,
+    ) -> ConnectionSpec:
+        values = self.list()
+        if connection_id:
+            match = next((item for item in values if item.connection_id == connection_id), None)
+            if not match:
+                raise ValueError(f"unknown EDA connection: {connection_id}")
+            if eda and match.eda != eda:
+                raise ValueError(f"connection {connection_id} does not target {eda}")
+            if origin_id and match.origin_id not in {None, origin_id}:
+                raise ValueError(f"connection {connection_id} does not target origin {origin_id}")
+            return match
+        if origin_id:
+            matches = [
+                item
+                for item in values
+                if item.origin_id == origin_id and (not eda or item.eda == eda)
+            ]
+            if len(matches) == 1:
+                return matches[0]
+            legacy = [item for item in values if not eda or item.eda == eda]
+            if len(matches) == 0 and len(legacy) == 1 and legacy[0].origin_id is None:
+                return legacy[0]
+            raise ValueError(
+                f"origin {origin_id} resolves to {len(matches)} connections; "
+                "register one exact origin binding"
+            )
+        matches = [item for item in values if not eda or item.eda == eda]
+        if len(matches) != 1:
+            target = eda or "requested EDA"
+            raise ValueError(
+                f"{target} resolves to {len(matches)} connections; provide a captured context "
+                "with connection_id or select one connection"
+            )
+        return matches[0]
+
+    def _write(self, values: list[ConnectionSpec]) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        payload = {
+            "schema_version": 1,
+            "connections": [
+                item.to_dict() for item in sorted(values, key=lambda x: x.connection_id)
+            ],
+        }
+        handle, temporary = tempfile.mkstemp(
+            prefix="connections-", suffix=".json", dir=self.path.parent
+        )
+        try:
+            with os.fdopen(handle, "w", encoding="utf-8") as stream:
+                json.dump(payload, stream, indent=2, sort_keys=True)
+                stream.write("\n")
+            os.replace(temporary, self.path)
+        finally:
+            if os.path.exists(temporary):
+                os.unlink(temporary)