plm-engine-core 0.1.0a0__py3-none-any.whl

plm_engine_core/__init__.py

@@ -0,0 +1,24 @@
+"""plm-engine-core — TracePulse PLM Engine Core package (US-CR.1 scaffold).
+
+Internally split into two sub-packages aligned with target architecture
+invariant #5 ("execution separated from expertise") and decision
+D-LOCKED-13:
+
+  * `control_plane/`  — governance, autonomy, HITL, run lifecycle,
+                        trace propagation. Owns *what is allowed*.
+  * `agent_runtime/`  — selector, dispatcher, retry, escalation.
+                        Owns *how skills execute*.
+
+One-way import contract: `control_plane` MUST NOT import from
+`agent_runtime`. Mechanical enforcement (import-linter rule) lands
+in US-CR.2; until then the rule is documented in README and observed
+by convention.
+
+US-CR.1 ships this scaffold deliberately empty — every other US-CR.*
+story (CR.0 identity middleware, CR.2 boundary lint, CR.3-6 policies,
+CR.7 MCP server, CR.8 OpenAPI, CR.9 federated manifest, CR.10 selector,
+CR.11 retry, CR.12 capability registry, CR.13 HITL) lands its
+implementation inside these clear, enforceable internal boundaries
+from day one.
+"""
+__version__ = "0.1.0-alpha"

plm_engine_core/agent_runtime/__init__.py

@@ -0,0 +1,31 @@
+"""plm_engine_core.agent_runtime — selector + dispatcher + retry +
+escalation (US-CR.1 scaffold).
+
+Owns *how skills execute*: skill selection, Kernel dispatch, retry
+orchestration on transient failures, escalation when retries
+exhaust. Downstream stories land here:
+
+  * US-CR.10 — skill selector → Kernel dispatch loopback (runtime side).
+  * US-CR.11 — externalised RetryPolicy module.
+
+`agent_runtime` may import from `plm_shared.*` (frozen contracts) and
+from `plm_engine_core.control_plane` is **forbidden** by the one-way
+import rule. Decisions about what is allowed live in `control_plane`;
+the runtime asks control_plane for verdicts but does not depend on
+its internals.
+
+The `__all__` placeholders below name the public surface downstream
+stories will populate. Importing any of them today raises
+`ImportError` because the modules don't exist yet — placeholder
+list is the contract, not a runtime shim.
+"""
+__all__ = [
+    # US-CR.10 — skill selection from a tenant + capability scope.
+    "selector",
+    # Kernel dispatch loop (runtime side of US-CR.10).
+    "dispatcher",
+    # US-CR.11 — externalised retry policy (taxonomy-aware).
+    "retry",
+    # Escalation when retries exhaust or autonomy gate denies.
+    "escalation",
+]

plm_engine_core/agent_runtime/dispatcher.py

@@ -0,0 +1,343 @@
+"""US-CR.10 — KernelDispatcher Protocol + V1 in-process adapter.
+
+Decision #51 (Conv M / Q-M2=(c) "Both"): dispatcher lives here and
+``mcp/tools.py::_impl_skill_invoke`` is a thin wrapper around it.
+
+**V1 transport scope.** The CR.10 §7.bis frozen wire contract names
+HTTP loopback at ``POST /v1/skills/{id}/invoke`` against a Wave 2
+Kernel stub. Wave 2 Conv A (D-CONV-M-4 closure) wires the actual
+HTTP round-trip:
+
+* :class:`KernelDispatcher` — the Protocol surface. Accepts an
+  invocation request + dispatch context, returns a result or
+  raises a typed terminal exception.
+* :class:`InProcessKernelDispatcher` — the V1 adapter. Behaviour:
+
+  - ``SKILL_KERNEL_LOOPBACK`` off (default) → returns
+    ``KERNEL_DISPATCH_DISABLED`` (CR.10 §AC#7).
+  - ``SKILL_KERNEL_LOOPBACK`` on → posts the dispatch request to the
+    plm-skill-kernel server (default ``http://127.0.0.1:8100``) and
+    returns the resulting :class:`DispatchResult`. The Kernel URL is
+    overridable via ``SKILL_KERNEL_URL``. ``httpx`` is imported
+    lazily so the off-path doesn't require the dep on PYTHONPATH.
+
+The Protocol surface is unchanged; only the V1.1 transport branch
+moved from a deferred placeholder to a real round-trip.
+
+Cancellation propagation (CR.10 §AC#5 + Decision #28 / CR.1b's
+third deferred consumer): the dispatch context carries an optional
+``RunTaskTracker`` + ``run_id``; the dispatcher checks
+``is_cancelled(run_id)`` before contacting the transport AND short-
+circuits the HTTP call when cancellation fires before the request
+is sent.
+"""
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+from typing import Any, Dict, Optional, Protocol
+
+from plm_shared.capability_registry import CapabilityVersion
+
+from ..control_plane.run_task_tracker import RunTaskTracker
+
+
+logger = logging.getLogger(__name__)
+
+
+# Default Kernel URL — Q-W2A-3 chose a standalone Kernel process on
+# port 8100; matches plm-skill-kernel/server.py:DEFAULT_PORT.
+_DEFAULT_KERNEL_URL = "http://127.0.0.1:8100"
+_KERNEL_HTTP_TIMEOUT_SECONDS = 30.0
+
+
+# ── Feature flag ─────────────────────────────────────────────────────────
+
+
+def _loopback_enabled() -> bool:
+    """Read the ``SKILL_KERNEL_LOOPBACK`` env flag.
+
+    Default off (CR.10 §AC#7). The flag exists from V1 so the
+    dispatcher layer is wire-compatible with the Wave 2 Kernel stub
+    swap; Conv M evaluates the flag to decide between
+    ``KERNEL_DISPATCH_DISABLED`` and the V1.1 stub.
+    """
+    return os.environ.get("SKILL_KERNEL_LOOPBACK", "").lower() in {
+        "1",
+        "true",
+        "on",
+        "yes",
+    }
+
+
+# ── Public types ─────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class DispatchRequest:
+    """Inputs to the dispatcher.
+
+    Mirrors :class:`plm_shared.kernel_api.v1.SkillInvocationRequest`
+    field names — V1 doesn't yet serialise; V1.1 will.
+    """
+
+    skill_id: str
+    skill_version: CapabilityVersion
+    arguments: Dict[str, Any]
+    tenant_id: str
+    autonomy_level: str
+    idempotency_key: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class DispatchContext:
+    """Per-call context — cancellation + trace.
+
+    Wired by CR.7's ``_impl_skill_invoke`` from the inbound MCP
+    ``ToolCallContext``.
+    """
+
+    run_id: Optional[str] = None
+    run_task_tracker: Optional[RunTaskTracker] = None
+    trace_id: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class DispatchResult:
+    """V1 typed dispatch result.
+
+    ``ok=True`` carries a JSON-serialisable ``payload``. ``ok=False``
+    carries the D-AUDIT-7 ``error_code`` so callers can map to
+    :class:`ErrorEnvelope` without an extra match.
+    """
+
+    ok: bool
+    payload: Optional[Dict[str, Any]] = None
+    error_code: Optional[str] = None
+    error_message: Optional[str] = None
+    cancelled: bool = False
+
+
+# ── Protocol ─────────────────────────────────────────────────────────────
+
+
+class KernelDispatcher(Protocol):
+    """V1 dispatcher surface (CR.10 §7)."""
+
+    async def dispatch(
+        self,
+        request: DispatchRequest,
+        context: DispatchContext,
+    ) -> DispatchResult:
+        ...
+
+
+# ── InProcessKernelDispatcher — V1 adapter ───────────────────────────────
+
+
+class InProcessKernelDispatcher:
+    """V1 adapter.
+
+    Behaviour:
+
+    * Cancellation check first (CR.10 §AC#5).
+    * If ``SKILL_KERNEL_LOOPBACK`` is off → ``KERNEL_DISPATCH_DISABLED``
+      (CR.10 §AC#7).
+    * If on → V1 returns a typed ``deferred_to=US-CR.10-V1.1`` payload
+      announcing the Wave 2 Kernel stub deferral. The Wave 2 swap
+      replaces this branch with the HTTP round-trip; the Protocol
+      surface stays unchanged.
+    """
+
+    async def dispatch(
+        self,
+        request: DispatchRequest,
+        context: DispatchContext,
+    ) -> DispatchResult:
+        # AC#5 — cancel-on-disconnect propagates through the dispatch.
+        if (
+            context.run_task_tracker is not None
+            and context.run_id is not None
+            and context.run_task_tracker.is_cancelled(context.run_id)
+        ):
+            return DispatchResult(
+                ok=True,
+                payload={
+                    "deferred": True,
+                    "reason": "run cancelled before dispatch",
+                    "deferred_to": "cancellation",
+                    "skill_id": request.skill_id,
+                    "skill_version": request.skill_version.version,
+                    "cancelled": True,
+                },
+                cancelled=True,
+            )
+
+        if not _loopback_enabled():
+            return DispatchResult(
+                ok=False,
+                error_code="KERNEL_DISPATCH_DISABLED",
+                error_message=(
+                    "SKILL_KERNEL_LOOPBACK is off; dispatch disabled in V1"
+                ),
+            )
+
+        # V1.1 transport (D-CONV-M-4 closure / Wave 2 Conv A item 8):
+        # POST to plm-skill-kernel's HTTP server. The deferred branch
+        # is GONE — the flag-on path is now a real round-trip.
+        return await self._dispatch_http_loopback(request, context)
+
+    async def _dispatch_http_loopback(
+        self,
+        request: DispatchRequest,
+        context: DispatchContext,
+    ) -> DispatchResult:
+        """V1.1 HTTP round-trip to plm-skill-kernel.
+
+        URL: ``${SKILL_KERNEL_URL or 127.0.0.1:8100}/v1/skills/{id}/invoke``.
+
+        Headers:
+
+        * ``X-Core-Caller`` — tenant_id is the V1 stand-in until the
+          V1.2 caller-UUID surface lands; matches the Conv F shape
+          where the middleware accepts a UUID-shaped opaque value.
+        * ``Idempotency-Key`` — propagated when the request carries one.
+        * ``traceparent`` — propagated from the dispatch context's
+          ``trace_id`` field (W3C format expected upstream).
+
+        Errors are mapped to typed :class:`DispatchResult` with a
+        D-AUDIT-7 ``error_code`` rather than raised — the dispatcher's
+        contract is "always returns a DispatchResult".
+        """
+        # Lazy import: the off-path doesn't need httpx, and even on-path
+        # tests can stub the import via monkeypatch.
+        try:
+            import httpx  # type: ignore[import-not-found]
+        except ImportError:
+            return DispatchResult(
+                ok=False,
+                error_code="KERNEL_DISPATCH_FAILED",
+                error_message=(
+                    "SKILL_KERNEL_LOOPBACK=on but httpx is not installed; "
+                    "install httpx>=0.27 in the Engine Core environment"
+                ),
+            )
+
+        kernel_url = os.environ.get("SKILL_KERNEL_URL", _DEFAULT_KERNEL_URL)
+        url = f"{kernel_url.rstrip('/')}/v1/skills/{request.skill_id}/invoke"
+        body = {
+            "payload": dict(request.arguments),
+            "version": request.skill_version.version,
+            "autonomy_hint": request.autonomy_level,
+        }
+        headers: Dict[str, str] = {
+            # Tenant-as-X-Core-Caller is the V1 stand-in until the
+            # V1.2 caller-UUID surface (W2 Conv C cross-package
+            # cleanup) lands; tenant_id is already a UUID at the
+            # middleware layer, so the receiver can treat it as one.
+            "X-Core-Caller": request.tenant_id,
+            "X-Tenant-Id": request.tenant_id,
+            "Content-Type": "application/json",
+        }
+        if request.idempotency_key:
+            headers["Idempotency-Key"] = request.idempotency_key
+        if context.trace_id:
+            headers["traceparent"] = context.trace_id
+        if context.run_id:
+            headers["X-Run-Id"] = context.run_id
+
+        try:
+            async with httpx.AsyncClient(
+                timeout=_KERNEL_HTTP_TIMEOUT_SECONDS
+            ) as client:
+                response = await client.post(url, json=body, headers=headers)
+        except httpx.TimeoutException as exc:
+            logger.warning("kernel dispatch timeout url=%s err=%s", url, exc)
+            return DispatchResult(
+                ok=False,
+                error_code="KERNEL_DISPATCH_TIMEOUT",
+                error_message=f"kernel dispatch timed out after {_KERNEL_HTTP_TIMEOUT_SECONDS}s",
+            )
+        except httpx.HTTPError as exc:
+            logger.warning("kernel dispatch http error url=%s err=%s", url, exc)
+            return DispatchResult(
+                ok=False,
+                error_code="KERNEL_DISPATCH_FAILED",
+                error_message=f"kernel transport error: {exc}",
+            )
+
+        # AC#5 - re-check cancellation after the round-trip; a long
+        # call may have been cancelled while in-flight.
+        if (
+            context.run_task_tracker is not None
+            and context.run_id is not None
+            and context.run_task_tracker.is_cancelled(context.run_id)
+        ):
+            return DispatchResult(
+                ok=True,
+                payload={
+                    "deferred": True,
+                    "reason": "run cancelled during dispatch",
+                    "deferred_to": "cancellation",
+                    "skill_id": request.skill_id,
+                    "skill_version": request.skill_version.version,
+                    "cancelled": True,
+                },
+                cancelled=True,
+            )
+
+        try:
+            envelope = response.json()
+        except ValueError:
+            return DispatchResult(
+                ok=False,
+                error_code="KERNEL_DISPATCH_FAILED",
+                error_message=(
+                    f"kernel returned non-JSON response (status={response.status_code})"
+                ),
+            )
+
+        if response.status_code >= 500:
+            return DispatchResult(
+                ok=False,
+                error_code="KERNEL_DISPATCH_FAILED",
+                error_message=(
+                    f"kernel returned status {response.status_code}"
+                ),
+            )
+
+        ok = bool(envelope.get("ok"))
+        if not ok:
+            err = envelope.get("error") or {}
+            return DispatchResult(
+                ok=False,
+                error_code=err.get("error_code", "KERNEL_DISPATCH_FAILED"),
+                error_message=err.get(
+                    "message", "kernel dispatch failed without message"
+                ),
+            )
+
+        payload = envelope.get("result") or {}
+        # Stamp skill identity for downstream consumers + match the
+        # placeholder shape Conv M was returning (skill_id /
+        # skill_version are the V1 contract on success).
+        if isinstance(payload, dict):
+            payload.setdefault("skill_id", request.skill_id)
+            payload.setdefault("skill_version", request.skill_version.version)
+
+        cancelled_flag = bool(envelope.get("cancelled") or False)
+        return DispatchResult(
+            ok=True,
+            payload=payload,
+            cancelled=cancelled_flag,
+        )
+
+
+__all__ = [
+    "DispatchContext",
+    "DispatchRequest",
+    "DispatchResult",
+    "InProcessKernelDispatcher",
+    "KernelDispatcher",
+]

plm_engine_core/agent_runtime/selector.py

@@ -0,0 +1,154 @@
+"""US-CR.10 — SkillSelector Protocol + RegistrySkillSelector V1 adapter.
+
+Decision #51 (Conv M / Q-M2=(c) "Both"): selector lives in
+``agent_runtime/`` per CR.10 §7 + the ``__init__.py`` placeholder
+laid down by CR.1; CR.7's ``_impl_skill_invoke`` is a thin wiring
+delegating into this module.
+
+V1 selector reads CR.12's :class:`CapabilityRegistry` to resolve
+``(skill_id, version)`` to a runnable :class:`SkillResolution`.
+Per CR.10 §6 main business rules: deterministic resolution,
+explicit version honoured, gating refusals short-circuit dispatch.
+
+LLM-based or heuristic routing is V1.1+ (CR.10 §"Functional out
+of scope"). V1 is registry-driven only.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Optional, Protocol
+
+from plm_shared.capability_registry import (
+    AutonomyLevel,
+    CapabilityVersion,
+    GatingDecision,
+)
+
+from ..control_plane.capability_registry import (
+    CapabilityNoSelectableVersionError,
+    CapabilityNotFoundError,
+    CapabilityRegistry,
+    CapabilityRetiredError,
+)
+
+
+# ── Public types ──────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class SkillResolution:
+    """Selector outcome — the resolved skill version + the gating verdict.
+
+    ``gating.allowed`` is True iff the call may proceed; the dispatcher
+    refuses dispatch when False and surfaces the gating reason.
+    """
+
+    skill_id: str
+    version: CapabilityVersion
+    gating: GatingDecision
+
+
+@dataclass(frozen=True)
+class SelectorError:
+    """Typed error from the selector path.
+
+    Carries a D-AUDIT-7 code so the dispatcher / MCP tool can convert
+    it to an :class:`ErrorEnvelope` directly.
+    """
+
+    code: str
+    message: str
+    skill_id: str
+    requested_version: Optional[str] = None
+
+
+# ── Protocol ──────────────────────────────────────────────────────────────
+
+
+class SkillSelector(Protocol):
+    """V1 surface (CR.10 §7).
+
+    The selector resolves an intent + agent context to a single
+    runnable skill version. ``select`` returns a typed result OR a
+    typed error; bare exceptions never escape.
+    """
+
+    def select(
+        self,
+        skill_id: str,
+        *,
+        skill_version: Optional[str] = None,
+        tenant_id: str,
+        autonomy_level: AutonomyLevel,
+        granted_scopes: Optional[List[str]] = None,
+    ) -> SkillResolution | SelectorError:
+        ...
+
+
+# ── RegistrySkillSelector — V1 adapter ───────────────────────────────────
+
+
+class RegistrySkillSelector:
+    """V1 selector reading the dynamic Capability Registry."""
+
+    def __init__(self, registry: CapabilityRegistry) -> None:
+        self._registry = registry
+
+    def select(
+        self,
+        skill_id: str,
+        *,
+        skill_version: Optional[str] = None,
+        tenant_id: str,
+        autonomy_level: AutonomyLevel,
+        granted_scopes: Optional[List[str]] = None,
+    ) -> SkillResolution | SelectorError:
+        try:
+            ver = self._registry.negotiate_version(
+                skill_id,
+                requested_version=skill_version,
+                tenant_id=tenant_id,
+            )
+        except CapabilityNotFoundError:
+            return SelectorError(
+                code="SKILL_NOT_FOUND",
+                message=f"no skill registered for id={skill_id!r}",
+                skill_id=skill_id,
+                requested_version=skill_version,
+            )
+        except CapabilityRetiredError:
+            return SelectorError(
+                code="SKILL_VERSION_NOT_FOUND",
+                message=(
+                    f"skill {skill_id!r} version {skill_version!r} is retired"
+                ),
+                skill_id=skill_id,
+                requested_version=skill_version,
+            )
+        except CapabilityNoSelectableVersionError:
+            return SelectorError(
+                code="CAPABILITY_NO_SELECTABLE_VERSION",
+                message=(
+                    f"no selectable version for skill {skill_id!r}"
+                ),
+                skill_id=skill_id,
+                requested_version=skill_version,
+            )
+
+        gating = self._registry.is_gated(
+            skill_id,
+            version=ver.version,
+            tenant_id=tenant_id,
+            autonomy_level=autonomy_level,
+            granted_scopes=granted_scopes,
+        )
+
+        return SkillResolution(skill_id=skill_id, version=ver, gating=gating)
+
+
+__all__ = [
+    "RegistrySkillSelector",
+    "SelectorError",
+    "SkillResolution",
+    "SkillSelector",
+]

plm_engine_core/cli/__init__.py

@@ -0,0 +1,64 @@
+"""plm-cli — operator tooling for plm-engine-core (US-CR.0 PR-3 / Conv F).
+
+Lives at the engine-core top level alongside the future Core MCP
+server (US-CR.7) and OpenAPI artefact (US-CR.8) — neither
+control_plane nor agent_runtime, per the CR.1 module placement
+convention. CR.2's import-linter Forbidden contracts do not apply
+here (the CLI is metadata, not a control_plane / agent_runtime
+runtime path).
+
+V1 commands:
+  plm-cli auth issue-token  — mint an HS256 dev/staging token
+                              consumed by IdentityMiddleware
+                              (round-trips through PR-2's provider).
+
+Future stories add subcommands (e.g. `plm-cli mcp serve` for CR.7);
+the dispatcher below is a flat `command subcommand` shape that can
+absorb new top-level commands without restructuring.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Optional, Sequence
+
+from . import auth
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """Argparse tree: `plm-cli {auth} {subcommand} ...`."""
+    parser = argparse.ArgumentParser(
+        prog="plm-cli",
+        description=(
+            "Operator tooling for plm-engine-core. V1 ships the "
+            "`auth` group; future stories add `mcp`, `policies`, etc."
+        ),
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    auth_parser = sub.add_parser(
+        "auth",
+        help="Issue / inspect identity tokens (HS256 dev path).",
+    )
+    auth.add_subparsers(auth_parser)
+
+    return parser
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    """Entry point used by both the console_script and tests.
+
+    Tests should pass `argv=[...]` to drive the parser directly.
+    Console-script use leaves argv=None; argparse reads sys.argv.
+    Returns the process exit code (0 = success, non-zero = error).
+    """
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    if args.command == "auth":
+        return auth.dispatch(args)
+    parser.error(f"unknown command: {args.command}")
+    return 2  # unreachable; argparse exits
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

plm_engine_core/cli/__main__.py

@@ -0,0 +1,15 @@
+"""Module-execution entry: `python -m plm_engine_core.cli ...`.
+
+Mirrors the console_script `plm-cli` registered in pyproject.toml,
+useful when the script-shim isn't on PATH (fresh editable install,
+CI containers without entry-point shims).
+"""
+from __future__ import annotations
+
+import sys
+
+from . import main
+
+
+if __name__ == "__main__":
+    sys.exit(main())