logplane 0.13.0__py3-none-any.whl

logplane/__init__.py

@@ -0,0 +1,113 @@
+"""Stable public integration SDK for logplane.
+
+Application code should import from this package (or ``logplane.adapters``
+and ``logplane.protocol``) rather than from implementation modules.
+"""
+
+from logplane.adoption import (
+    AdoptionBridge,
+    AdoptionMode,
+    CanarySelector,
+    ExecutionOwner,
+    ExternalOrigin,
+    OwnershipDecision,
+    decide_ownership,
+)
+from logplane.artifacts import (
+    ArtifactError,
+    ArtifactIntegrityError,
+    ArtifactStore,
+    validate_artifact_ref,
+)
+from logplane.client import BusClient, BusProtocolError
+from logplane.conformance import (
+    ConformanceCheck,
+    ConformanceReport,
+    check_executor,
+    probe_assignment,
+)
+from logplane.executor_protocol import (
+    CURRENT_PROTOCOL_VERSION,
+    PROTOCOL_NAME,
+    SUPPORTED_PROTOCOL_VERSIONS,
+    assignment_message,
+    cancellation_message,
+    outcome_message,
+    parse_assignment_message,
+    parse_outcome_message,
+)
+from logplane.executors import (
+    AssignmentContext,
+    Blocked,
+    Completed,
+    Executor,
+    Outcome,
+    PermanentFailure,
+    RetryableFailure,
+)
+from logplane.integration import (
+    CliAgentAdapter,
+    CliAgentConfig,
+    HttpAgentAdapter,
+    HttpAgentConfig,
+    IntegrationConfig,
+    PythonAgentAdapter,
+    load_python_target,
+)
+from logplane.runtime import WorkerRuntime
+from logplane.scheduling import (
+    DEFAULT_TASK_PRIORITY,
+    TASK_PRIORITY_CLASSES,
+    validate_task_priority,
+)
+from logplane.telemetry import BusTelemetrySink, ProducerIdentity, TelemetrySink
+
+
+__all__ = [
+    "AdoptionBridge",
+    "AdoptionMode",
+    "ArtifactError",
+    "ArtifactIntegrityError",
+    "ArtifactStore",
+    "AssignmentContext",
+    "Blocked",
+    "BusClient",
+    "BusProtocolError",
+    "BusTelemetrySink",
+    "CURRENT_PROTOCOL_VERSION",
+    "CanarySelector",
+    "CliAgentAdapter",
+    "CliAgentConfig",
+    "Completed",
+    "ConformanceCheck",
+    "ConformanceReport",
+    "ExecutionOwner",
+    "Executor",
+    "ExternalOrigin",
+    "HttpAgentAdapter",
+    "HttpAgentConfig",
+    "IntegrationConfig",
+    "Outcome",
+    "OwnershipDecision",
+    "PROTOCOL_NAME",
+    "PermanentFailure",
+    "ProducerIdentity",
+    "PythonAgentAdapter",
+    "RetryableFailure",
+    "SUPPORTED_PROTOCOL_VERSIONS",
+    "DEFAULT_TASK_PRIORITY",
+    "TASK_PRIORITY_CLASSES",
+    "TelemetrySink",
+    "WorkerRuntime",
+    "assignment_message",
+    "cancellation_message",
+    "check_executor",
+    "decide_ownership",
+    "load_python_target",
+    "outcome_message",
+    "parse_assignment_message",
+    "parse_outcome_message",
+    "probe_assignment",
+    "validate_task_priority",
+    "validate_artifact_ref",
+]

logplane/__main__.py

@@ -0,0 +1,5 @@
+"""Allow ``python -m logplane`` as an alternative to the ``logplane`` command."""
+
+from logplane.cli import main
+
+raise SystemExit(main())

logplane/adapter_check.py

@@ -0,0 +1,209 @@
+"""Internal process boundary for CLI probes; not an adapter security sandbox."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import math
+import os
+from pathlib import Path
+import signal
+import stat
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+
+DEFAULT_CHECK_TIMEOUT = 30.0
+MAX_REPORT_BYTES = 64 * 1024
+CLEANUP_GRACE_SECONDS = 0.25
+GROUP_INSPECTION_SECONDS = 1.0
+
+
+def _darwin_group_exited(process: subprocess.Popen) -> bool:
+    """Prove a denied Darwin group signal has no executing target left.
+
+    XNU killpg1 filters SZOMB members before counting signalable processes, so
+    a zombie-only group can return EPERM rather than ESRCH. Never interpret
+    EPERM alone (or just the leader's exit) as successful descendant cleanup.
+    """
+    if sys.platform != 'darwin' or process.poll() is None:
+        return False
+    try:
+        result = subprocess.run(
+            ['/bin/ps', '-A', '-o', 'pgid=,stat='], stdin=subprocess.DEVNULL,
+            capture_output=True, text=True, timeout=GROUP_INSPECTION_SECONDS,
+            env={'LC_ALL': 'C', 'PATH': '/usr/bin:/bin'})
+        if result.returncode != 0 or not result.stdout.strip():
+            return False
+        for line in result.stdout.splitlines():
+            fields = line.split()
+            if len(fields) != 2 or not fields[0].isdigit():
+                return False
+            if int(fields[0]) == process.pid and not fields[1].startswith('Z'):
+                return False
+        return True
+    except (OSError, subprocess.TimeoutExpired, UnicodeError):
+        return False
+
+
+def _signal_group(process: subprocess.Popen, sig: int) -> bool:
+    """Return false for an absent/exited group; fail closed on denied cleanup."""
+    try:
+        os.killpg(process.pid, sig)
+        return True
+    except ProcessLookupError:
+        return False
+    except PermissionError as exc:
+        if _darwin_group_exited(process):
+            return False
+        raise PermissionError(
+            f'adapter cleanup could not signal process group {process.pid}; '
+            'no-live-members verification failed; child processes may remain') from exc
+
+
+def _stop_group(process: subprocess.Popen) -> None:
+    # Do not skip group cleanup when its leader has already exited: an adapter
+    # may have left a child alive. Only our newly-created process group is used.
+    if not _signal_group(process, signal.SIGTERM):
+        process.wait(timeout=1)
+        return
+    try:
+        process.wait(timeout=CLEANUP_GRACE_SECONDS)
+    except subprocess.TimeoutExpired:
+        pass
+    # A child can ignore TERM even if the leader exits promptly.
+    _signal_group(process, signal.SIGKILL)
+    process.wait(timeout=1)
+
+
+def run_adapter_check(*, python_target: str | None = None,
+                      integration_config: str | None = None,
+                      timeout: float = DEFAULT_CHECK_TIMEOUT):
+    """Bound loading, execution, and close; return the ordinary conformance report.
+
+    Library callers with already-created executors still use the synchronous
+    conformance.check_executor(). This internal helper loads CLI targets afresh.
+    """
+    from logplane.conformance import ConformanceCheck, ConformanceReport
+
+    if bool(python_target) == bool(integration_config):
+        raise ValueError('choose exactly one Python target or integration config')
+    if isinstance(timeout, bool) or not math.isfinite(timeout) or timeout <= 0:
+        raise ValueError('adapter check timeout must be a positive finite number')
+
+    def failed(name, detail):
+        return ConformanceReport((ConformanceCheck(name, False, detail),))
+
+    def interrupted(*_):
+        raise KeyboardInterrupt
+
+    main_thread = threading.current_thread() is threading.main_thread()
+    previous = signal.getsignal(signal.SIGTERM) if main_thread else None
+    process = None
+    with tempfile.TemporaryDirectory(prefix='logplane-adapter-check-') as tmp:
+        report_path = Path(tmp) / 'report.json'
+        args = [sys.executable, '-m', 'logplane.adapter_check', '--report', str(report_path)]
+        # Resolve/read the adapter configuration only in the timed child.
+        args += (['--python-target', python_target] if python_target
+                 else ['--config', str(integration_config)])
+        try:
+            if main_thread:
+                signal.signal(signal.SIGTERM, interrupted)
+            deadline = time.monotonic() + timeout
+            process = subprocess.Popen(
+                args, stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL, start_new_session=True)
+            try:
+                process.wait(timeout=max(0, deadline - time.monotonic()))
+            except subprocess.TimeoutExpired:
+                return failed('probe timeout',
+                              f'adapter check exceeded {timeout:g}s during loading, execution, '
+                              'or cleanup; check for blocking hooks or use --timeout with '
+                              'a larger value for an intentionally slow trusted probe')
+            if process.returncode != 0:
+                return failed('probe process',
+                              f'adapter check process exited with status {process.returncode} '
+                              'before a valid result; check adapter startup and native dependencies')
+            try:
+                # A broken adapter must not turn the result channel into a
+                # blocking FIFO/device or a symlink after it exits.
+                descriptor = os.open(report_path, os.O_RDONLY | os.O_NONBLOCK | os.O_NOFOLLOW)
+                with os.fdopen(descriptor, 'rb') as stream:
+                    if not stat.S_ISREG(os.fstat(stream.fileno()).st_mode):
+                        raise ValueError('report is not a regular file')
+                    raw = stream.read(MAX_REPORT_BYTES + 1)
+                if len(raw) > MAX_REPORT_BYTES:
+                    raise ValueError('oversized report')
+                envelope = json.loads(raw)
+                if envelope.get('kind') == 'error':
+                    error = envelope['message']
+                    if not isinstance(error, str):
+                        raise ValueError('invalid error')
+                else:
+                    error = None
+                    value = envelope['report']
+                    checks = value['checks']
+                    outcome = value['outcome_type']
+                    if (envelope.get('kind') != 'report' or not isinstance(checks, list)
+                            or not checks or (outcome is not None and not isinstance(outcome, str))):
+                        raise ValueError('invalid report')
+                    decoded = []
+                    for check in checks:
+                        if (set(check) != {'name', 'ok', 'detail', 'required'}
+                                or not isinstance(check['name'], str)
+                                or not isinstance(check['detail'], str)
+                                or type(check['ok']) is not bool
+                                or type(check['required']) is not bool):
+                            raise ValueError('invalid check')
+                        decoded.append(ConformanceCheck(**check))
+            except (OSError, ValueError, KeyError, TypeError, AttributeError):
+                return failed('probe report', 'adapter check returned a missing, oversized, or invalid report')
+            if error is not None:
+                raise ValueError(error)
+            return ConformanceReport(tuple(decoded), outcome)
+        finally:
+            try:
+                if process is not None:
+                    _stop_group(process)
+            finally:
+                if main_thread:
+                    signal.signal(signal.SIGTERM, previous)
+
+
+def _child(args) -> None:
+    # All adapter-controlled hooks, including imports and constructors, stay
+    # within this process and therefore within the parent's deadline.
+    from logplane.conformance import check_executor
+    from logplane.integration import IntegrationConfig, PythonAgentAdapter, load_python_target
+
+    try:
+        if args.config:
+            executor = IntegrationConfig.from_file(args.config).build_executor()
+        else:
+            target = load_python_target(args.python_target)
+            executor = target if callable(getattr(target, 'execute', None)) else PythonAgentAdapter(target)
+        envelope = {'kind': 'report', 'report': check_executor(executor).to_dict()}
+    except Exception as exc:
+        envelope = {'kind': 'error', 'message': f'{type(exc).__name__}: {exc}'[:2048]}
+    encoded = json.dumps(envelope, allow_nan=False).encode('utf-8')
+    if len(encoded) > MAX_REPORT_BYTES:
+        envelope = {'kind': 'report', 'report': {
+            'outcome_type': None,
+            'checks': [{'name': 'probe report', 'ok': False, 'required': True,
+                        'detail': 'adapter check report exceeds the 64 KiB limit'}]}}
+        encoded = json.dumps(envelope).encode('utf-8')
+    # The enclosing directory is private. Direct adapter stdout/stderr are
+    # discarded, so noise or inherited pipe handles cannot corrupt/block JSON.
+    with open(args.report, 'xb') as stream:
+        stream.write(encoded)
+
+
+if __name__ == '__main__':
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--report', required=True)
+    group = parser.add_mutually_exclusive_group(required=True)
+    group.add_argument('--python-target')
+    group.add_argument('--config')
+    _child(parser.parse_args())

logplane/adapters.py

@@ -0,0 +1,21 @@
+"""Public adapter imports kept separate for discoverability."""
+
+from logplane.integration import (
+    CliAgentAdapter,
+    CliAgentConfig,
+    HttpAgentAdapter,
+    HttpAgentConfig,
+    IntegrationConfig,
+    PythonAgentAdapter,
+    load_python_target,
+)
+
+__all__ = [
+    "CliAgentAdapter",
+    "CliAgentConfig",
+    "HttpAgentAdapter",
+    "HttpAgentConfig",
+    "IntegrationConfig",
+    "PythonAgentAdapter",
+    "load_python_target",
+]

logplane/adoption.py

@@ -0,0 +1,231 @@
+"""Safe rollout helpers for controlled, shadow, and canary adoption."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any, Iterable, Mapping, Optional
+
+from logplane.client import BusClient
+from logplane.scheduling import validate_task_priority
+
+
+class AdoptionMode(str, Enum):
+    CONTROLLED = "controlled"
+    SHADOW = "shadow"
+    CANARY = "canary"
+
+
+class ExecutionOwner(str, Enum):
+    # Stored in event history under the pre-0.13 project name; keep the
+    # value unchanged so existing logs replay with the same ownership.
+    AGENT_BUS = "agent-bus"
+    EXTERNAL = "external"
+
+
+@dataclass(frozen=True)
+class ExternalOrigin:
+    system: str
+    task_ref: str
+
+    def __post_init__(self) -> None:
+        for field_name, value in (
+            ("system", self.system),
+            ("task_ref", self.task_ref),
+        ):
+            if not isinstance(value, str) or not value.strip():
+                raise ValueError(f"{field_name} must be a non-empty string")
+            if len(value) > 128:
+                raise ValueError(f"{field_name} must not exceed 128 characters")
+
+    @property
+    def key(self) -> str:
+        return json.dumps(
+            [self.system, self.task_ref],
+            ensure_ascii=False,
+            separators=(",", ":"),
+        )
+
+    def to_dict(self) -> dict:
+        return {"system": self.system, "task_ref": self.task_ref}
+
+
+@dataclass(frozen=True)
+class OwnershipDecision:
+    mode: AdoptionMode
+    owner: ExecutionOwner
+
+    def to_dict(self) -> dict:
+        return {"mode": self.mode.value, "owner": self.owner.value}
+
+
+class CanarySelector:
+    """Deterministically select external tasks using a stable hash."""
+
+    def __init__(
+        self,
+        percentage: float,
+        *,
+        namespace: str = "default",
+        include_refs: Iterable[str] = (),
+    ):
+        if (
+            not isinstance(percentage, (int, float))
+            or isinstance(percentage, bool)
+            or not 0 <= percentage <= 100
+        ):
+            raise ValueError("percentage must be between 0 and 100")
+        if not isinstance(namespace, str) or not namespace.strip():
+            raise ValueError("namespace must be a non-empty string")
+        self.basis_points = round(float(percentage) * 100)
+        self.namespace = namespace
+        if isinstance(include_refs, (str, bytes)):
+            raise ValueError("include_refs must be an iterable of task references")
+        self.include_refs = frozenset(include_refs)
+        if not all(isinstance(item, str) and item for item in self.include_refs):
+            raise ValueError("include_refs must contain non-empty strings")
+
+    def selects(self, origin: ExternalOrigin) -> bool:
+        if origin.task_ref in self.include_refs:
+            return True
+        digest = hashlib.sha256(
+            json.dumps(
+                [self.namespace, origin.system, origin.task_ref],
+                ensure_ascii=False,
+                separators=(",", ":"),
+            ).encode("utf-8")
+        ).digest()
+        bucket = int.from_bytes(digest[:8], "big") % 10_000
+        return bucket < self.basis_points
+
+
+def decide_ownership(
+    mode: AdoptionMode,
+    origin: ExternalOrigin,
+    selector: Optional[CanarySelector] = None,
+) -> OwnershipDecision:
+    if not isinstance(mode, AdoptionMode):
+        mode = AdoptionMode(mode)
+    if mode is AdoptionMode.CONTROLLED:
+        return OwnershipDecision(mode, ExecutionOwner.AGENT_BUS)
+    if mode is AdoptionMode.SHADOW:
+        return OwnershipDecision(mode, ExecutionOwner.EXTERNAL)
+    if selector is None:
+        raise ValueError("canary mode requires a CanarySelector")
+    owner = (
+        ExecutionOwner.AGENT_BUS
+        if selector.selects(origin)
+        else ExecutionOwner.EXTERNAL
+    )
+    return OwnershipDecision(mode, owner)
+
+
+class AdoptionBridge:
+    """Record one immutable ownership decision for external work.
+
+    The same actor/idempotency key is used whether the decision is bus-owned
+    or external. Re-evaluating an origin to a different owner therefore causes
+    an idempotency conflict instead of silently creating dual ownership.
+    """
+
+    def __init__(self, bus: BusClient):
+        self.bus = bus
+
+    def adopt(
+        self,
+        *,
+        origin: ExternalOrigin,
+        title: str,
+        mode: AdoptionMode,
+        selector: Optional[CanarySelector] = None,
+        context: Optional[Mapping[str, Any]] = None,
+        required_capabilities: Iterable[str] = (),
+        max_retries: Optional[int] = None,
+        priority: Optional[str] = None,
+        not_before: Optional[float] = None,
+        deadline_at: Optional[float] = None,
+        correlation_id: Optional[str] = None,
+    ) -> dict:
+        if not isinstance(title, str) or not title.strip():
+            raise ValueError("title must be a non-empty string")
+        normalized_context = self._json_object(
+            context if context is not None else {},
+            "context",
+        )
+        capabilities = tuple(dict.fromkeys(required_capabilities))
+        if not all(isinstance(item, str) and item.strip() for item in capabilities):
+            raise ValueError("required_capabilities must contain non-empty strings")
+        if max_retries is not None and (
+            not isinstance(max_retries, int)
+            or isinstance(max_retries, bool)
+            or max_retries < 0
+        ):
+            raise ValueError("max_retries must be a non-negative integer")
+        if priority is not None:
+            priority = validate_task_priority(priority)
+        if not_before is not None and (
+            not isinstance(not_before, (int, float))
+            or isinstance(not_before, bool)
+            or not math.isfinite(not_before)
+            or not_before <= 0
+        ):
+            raise ValueError("not_before must be a positive finite timestamp")
+        if deadline_at is not None and (
+            not isinstance(deadline_at, (int, float))
+            or isinstance(deadline_at, bool)
+            or not math.isfinite(deadline_at)
+            or deadline_at <= 0
+        ):
+            raise ValueError("deadline_at must be a positive finite timestamp")
+        if (
+            not_before is not None
+            and deadline_at is not None
+            and not_before >= deadline_at
+        ):
+            raise ValueError("not_before must be earlier than deadline_at")
+
+        decision = decide_ownership(mode, origin, selector)
+        payload = {
+            "title": title,
+            "context": normalized_context,
+            "required_capabilities": list(capabilities),
+            "external_origin": origin.to_dict(),
+            "ownership": decision.to_dict(),
+        }
+        if max_retries is not None:
+            payload["retry_policy"] = {"max_retries": max_retries}
+        if priority is not None:
+            payload["priority"] = priority
+        if not_before is not None:
+            payload["not_before"] = float(not_before)
+        if deadline_at is not None:
+            payload["deadline_at"] = float(deadline_at)
+
+        digest = hashlib.sha256(origin.key.encode("utf-8")).hexdigest()
+        idempotency_key = f"adopt:{digest}"
+        if decision.owner is ExecutionOwner.AGENT_BUS:
+            topic = "task.created"
+            effective_correlation = correlation_id
+        else:
+            topic = "integration.task_observed"
+            effective_correlation = correlation_id or f"external:{digest[:24]}"
+        return self.bus.publish(
+            topic,
+            payload,
+            idempotency_key=idempotency_key,
+            correlation_id=effective_correlation,
+        )
+
+    @staticmethod
+    def _json_object(value: object, field_name: str) -> dict:
+        if not isinstance(value, Mapping):
+            raise ValueError(f"{field_name} must be a JSON object")
+        try:
+            return json.loads(json.dumps(dict(value), allow_nan=False))
+        except (TypeError, ValueError) as exc:
+            raise ValueError(
+                f"{field_name} must contain JSON-compatible values"
+            ) from exc