monoid-agent-kernel 0.16.1__py3-none-any.whl

monoid_agent_kernel/conformance/__init__.py

@@ -0,0 +1,32 @@
+"""Conformance profile metadata and harness protocols."""
+
+from .harness import (
+    BackendHarness,
+    CapabilityHarness,
+    ConformanceHarness,
+    ControlPlaneHarness,
+    DurableRunnerHarness,
+    GatewayHarness,
+    MessageFabricHarness,
+    MultiAgentBackendHarness,
+    SideEffectHarness,
+    ToolAgentHarness,
+)
+from .profiles import PROFILES, PROFILE_BY_ID, ProfileMetadata, get_profile
+
+__all__ = [
+    "BackendHarness",
+    "CapabilityHarness",
+    "ConformanceHarness",
+    "ControlPlaneHarness",
+    "DurableRunnerHarness",
+    "GatewayHarness",
+    "MessageFabricHarness",
+    "MultiAgentBackendHarness",
+    "SideEffectHarness",
+    "ToolAgentHarness",
+    "PROFILES",
+    "PROFILE_BY_ID",
+    "ProfileMetadata",
+    "get_profile",
+]

monoid_agent_kernel/conformance/harness.py

@@ -0,0 +1,209 @@
+"""Protocols implemented by conformance test adapters."""
+
+from __future__ import annotations
+
+from typing import Any, Mapping, Protocol, Sequence, runtime_checkable
+
+JsonObject = Mapping[str, Any]
+
+
+@runtime_checkable
+class ConformanceHarness(Protocol):
+    """Common metadata exposed by every conformance harness."""
+
+    @property
+    def harness_id(self) -> str:
+        """Stable identifier used in test output."""
+
+    @property
+    def supported_profiles(self) -> Sequence[str]:
+        """Profile ids the harness intends to run."""
+
+
+@runtime_checkable
+class BackendHarness(ConformanceHarness, Protocol):
+    """Raw backend operations kept for compatibility and custom harnesses."""
+
+    def submit_run(self, request: JsonObject) -> JsonObject:
+        """Submit a run and return a handle containing at least run id and token."""
+
+    def status(self, run_id: str, token: str) -> JsonObject:
+        """Return the backend status projection for a run."""
+
+    def events(self, run_id: str, token: str, *, from_seq: int = 0, limit: int | None = None) -> JsonObject:
+        """Return a page of run events."""
+
+    def descendant_events(
+        self,
+        run_id: str,
+        token: str,
+        descendant_run_id: str,
+        *,
+        from_seq: int = 0,
+        limit: int | None = None,
+    ) -> JsonObject:
+        """Return a page of events for one authorized descendant run."""
+
+    def diagnostics(self, run_id: str, token: str, *, event_limit: int = 50) -> JsonObject:
+        """Return the diagnostics aggregate for a run."""
+
+    def result(self, run_id: str, token: str) -> JsonObject:
+        """Return the backend run result projection."""
+
+    def runtime_config(self, run_id: str, token: str) -> JsonObject:
+        """Return the current runtime config projection for a run."""
+
+    def replace_runtime_config(
+        self,
+        run_id: str,
+        token: str,
+        config: JsonObject,
+        *,
+        expected_version: int,
+        issuer: str,
+        reason: str,
+    ) -> JsonObject:
+        """Replace the runtime config for a live run."""
+
+    def resume_run(self, run_id: str, token: str) -> JsonObject:
+        """Materialize and resume one run from durable recovery metadata."""
+
+    def recover_runs(self) -> Sequence[str]:
+        """Recover all discoverable parked runs for this harness instance."""
+
+    def restart(self, *, local_state: str = "same") -> BackendHarness:
+        """Return a fresh harness instance over the same durable state."""
+
+    def task_result(self, run_id: str, token: str, task_id: str) -> JsonObject:
+        """Return the stored result for one backend task."""
+
+    def dispatch(self, command: JsonObject) -> JsonObject:
+        """Dispatch one backend control command."""
+
+
+@runtime_checkable
+class ToolAgentHarness(ConformanceHarness, Protocol):
+    """Tool-agent behavior cases."""
+
+    def run_tool_surface_admission_case(self) -> JsonObject:
+        """Run a tool surface admission case with a denied unavailable/quota-limited tool."""
+
+    def run_generic_ask_approval_case(self) -> JsonObject:
+        """Run generic authorization='ask' approval, denial, and stale replay cases."""
+
+
+@runtime_checkable
+class ControlPlaneHarness(ConformanceHarness, Protocol):
+    """Control-plane behavior cases."""
+
+    def run_control_decision_case(self) -> JsonObject:
+        """Run approve/deny decision handling and decision audit behavior."""
+
+    def run_control_audit_sequence_case(self) -> JsonObject:
+        """Run authorized, failed, unauthorized, and terminal audit sequencing behavior."""
+
+
+@runtime_checkable
+class DurableRunnerHarness(ConformanceHarness, Protocol):
+    """Durable-runner behavior cases."""
+
+    def run_event_sequence_case(self) -> JsonObject:
+        """Run event sequencing and diagnostics projection behavior."""
+
+    def run_recovery_metadata_case(self) -> JsonObject:
+        """Run recovery metadata and restart materialization behavior."""
+
+    def run_subagent_diagnostics_case(self) -> JsonObject:
+        """Run subagent diagnostics summary behavior."""
+
+
+@runtime_checkable
+class MultiAgentBackendHarness(ConformanceHarness, Protocol):
+    """Backend-visible multi-agent behavior cases."""
+
+    def run_subagent_boundary_case(self) -> JsonObject:
+        """Run subagent identity, trace, diagnostics, and accounting behavior."""
+
+    def run_subagent_capability_boundary_case(self) -> JsonObject:
+        """Run child capability-boundary behavior after parent revocation."""
+
+
+@runtime_checkable
+class SideEffectHarness(ConformanceHarness, Protocol):
+    """Backend operations used by side-effect-tool-agent profiles."""
+
+    def run_outbox_dispatched_case(self) -> JsonObject:
+        """Run a strict outbox side-effect case that stages and dispatches one request."""
+
+    def run_pending_recovery_case(self) -> JsonObject:
+        """Run a strict outbox side-effect case whose pending request survives restart."""
+
+    def run_strict_rejected_case(self) -> JsonObject:
+        """Run a strict external side-effect case rejected before handler execution."""
+
+    def run_idempotent_inline_case(self) -> JsonObject:
+        """Run an idempotent inline external side-effect case."""
+
+
+@runtime_checkable
+class MessageFabricHarness(ConformanceHarness, Protocol):
+    """Backend operations used by external agent message-fabric profiles."""
+
+    def run_two_peer_exchange_case(self) -> JsonObject:
+        """Run a two-peer exchange over the external-agent message fabric."""
+
+    def run_malformed_envelope_case(self) -> JsonObject:
+        """Run a malformed external-agent envelope rejection case."""
+
+    def run_duplicate_after_restart_case(self) -> JsonObject:
+        """Run a duplicate message case that survives restart."""
+
+    def run_peer_unavailable_case(self) -> JsonObject:
+        """Run a peer-unavailable case that leaves a retryable pending request."""
+
+
+@runtime_checkable
+class GatewayHarness(ConformanceHarness, Protocol):
+    """Gateway operation used by provider-gateway profiles."""
+
+    def call_gateway(
+        self,
+        capability: str,
+        payload: JsonObject,
+        *,
+        signed_capability: str | None = None,
+        signed_scope: JsonObject | None = None,
+    ) -> JsonObject:
+        """Call one gateway capability with a normalized payload."""
+
+
+@runtime_checkable
+class CapabilityHarness(ConformanceHarness, Protocol):
+    """Capability operations used by capability-security profiles."""
+
+    def request_capability(self, payload: JsonObject) -> JsonObject:
+        """Create or simulate one capability request."""
+
+    def grant_capability(self, request_id: str, lease: JsonObject) -> JsonObject:
+        """Grant a capability request with a lease payload."""
+
+    def deny_capability(self, request_id: str, result: JsonObject) -> JsonObject:
+        """Deny a capability request with a result payload."""
+
+    def revoke_capability(self, payload: JsonObject) -> JsonObject:
+        """Revoke capabilities according to the payload."""
+
+    def token_for(self, capability: str, *, now: float) -> str | None:
+        """Return the currently usable token handle for one capability."""
+
+    def valid_lease(self, capability: str, scope: JsonObject, *, now: float) -> JsonObject | None:
+        """Return a currently valid lease for one capability and scope."""
+
+    def export_revocations(self) -> JsonObject:
+        """Return serialized revocation state."""
+
+    def import_revocations(self, payload: JsonObject) -> JsonObject:
+        """Merge serialized revocation state and return the current export."""
+
+    def fork_child(self) -> CapabilityHarness:
+        """Return a child capability harness sharing revocation state."""

monoid_agent_kernel/conformance/profiles/__init__.py

@@ -0,0 +1,55 @@
+"""Conformance profile metadata."""
+
+from __future__ import annotations
+
+from ._metadata import ProfileMetadata
+from .capability_security import PROFILE as CAPABILITY_SECURITY
+from .control_plane import PROFILE as CONTROL_PLANE
+from .durable_runner import PROFILE as DURABLE_RUNNER
+from .message_fabric import PROFILE as MESSAGE_FABRIC
+from .minimal_agent import PROFILE as MINIMAL_AGENT
+from .multi_agent import PROFILE as MULTI_AGENT
+from .provider_gateway import PROFILE as PROVIDER_GATEWAY
+from .reference_full import PROFILE as REFERENCE_FULL
+from .side_effect_tool_agent import PROFILE as SIDE_EFFECT_TOOL_AGENT
+from .tool_agent import PROFILE as TOOL_AGENT
+
+PROFILES: tuple[ProfileMetadata, ...] = (
+    MINIMAL_AGENT,
+    TOOL_AGENT,
+    SIDE_EFFECT_TOOL_AGENT,
+    MESSAGE_FABRIC,
+    DURABLE_RUNNER,
+    CONTROL_PLANE,
+    CAPABILITY_SECURITY,
+    PROVIDER_GATEWAY,
+    MULTI_AGENT,
+    REFERENCE_FULL,
+)
+PROFILE_BY_ID: dict[str, ProfileMetadata] = {profile.profile_id: profile for profile in PROFILES}
+
+
+def get_profile(profile_id: str) -> ProfileMetadata:
+    """Return profile metadata by stable id."""
+    try:
+        return PROFILE_BY_ID[profile_id]
+    except KeyError as exc:
+        raise KeyError(f"unknown conformance profile: {profile_id}") from exc
+
+
+__all__ = [
+    "CAPABILITY_SECURITY",
+    "CONTROL_PLANE",
+    "DURABLE_RUNNER",
+    "MINIMAL_AGENT",
+    "MESSAGE_FABRIC",
+    "MULTI_AGENT",
+    "PROFILES",
+    "PROFILE_BY_ID",
+    "PROVIDER_GATEWAY",
+    "ProfileMetadata",
+    "REFERENCE_FULL",
+    "SIDE_EFFECT_TOOL_AGENT",
+    "TOOL_AGENT",
+    "get_profile",
+]

monoid_agent_kernel/conformance/profiles/_metadata.py

@@ -0,0 +1,16 @@
+"""Shared conformance profile metadata."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ProfileMetadata:
+    """Static description of one conformance profile."""
+
+    profile_id: str
+    title: str
+    summary: str
+    rule_ids: tuple[str, ...]
+    harnesses: tuple[str, ...]

monoid_agent_kernel/conformance/profiles/capability_security.py

@@ -0,0 +1,216 @@
+"""Capability-security profile metadata."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from monoid_agent_kernel.conformance.harness import CapabilityHarness
+
+from ._metadata import ProfileMetadata
+
+PROFILE = ProfileMetadata(
+    profile_id="capability-security",
+    title="Capability Security",
+    summary="Capability-gated runtime with scope narrowing, lease admission, denial, and revocation rules.",
+    rule_ids=(
+        "OR-01-SCOPE-RELATION",
+        "OR-02-CAPABILITY-BOUNDARY",
+        "OR-03-LEASE-ADMISSION",
+        "OR-04-REVOCATION-SCOPE",
+        "OR-06-CONTROL-AUDIT",
+        "OR-09-SUBAGENT-BOUNDARY",
+    ),
+    harnesses=("backend", "capability", "gateway"),
+)
+
+
+def assert_capability_security_lease_admission(harness: CapabilityHarness) -> None:
+    """Run the lease-admission conformance smoke matrix."""
+    request = harness.request_capability(
+        {
+            "capability": "web.search",
+            "scope": {"allowed_domains": ["*.example.test"], "max_results": 5},
+        }
+    )
+    request_id = str(request["request_id"])
+    lease = {
+        "lease_id": "lease_profile_ok",
+        "capability": "web.search",
+        "token_ref": "approved:web.search",
+        "expires_at": 4_102_444_800.0,
+        "issued_at": 1_700_000_000.0,
+        "max_expires_at": 4_102_445_000.0,
+        "durable": True,
+        "scope": {"allowed_domains": ["docs.example.test"], "max_results": 3},
+    }
+
+    admitted = harness.grant_capability(request_id, lease)
+    assert admitted["lease_id"] == lease["lease_id"]
+    assert admitted["capability"] == lease["capability"]
+    assert admitted["token_ref"] == lease["token_ref"]
+    assert admitted["issued_at"] == lease["issued_at"]
+    assert admitted["max_expires_at"] == lease["max_expires_at"]
+    assert admitted["durable"] is True
+    assert admitted["scope"] == lease["scope"]
+
+    widened = harness.request_capability(
+        {"capability": "web.search", "scope": {"allowed_domains": ["docs.example.test"], "max_results": 2}}
+    )
+    _assert_raises(
+        lambda: harness.grant_capability(
+            str(widened["request_id"]),
+            {
+                "capability": "web.search",
+                "token_ref": "approved:web.search",
+                "expires_at": 4_102_444_800.0,
+                "scope": {"allowed_domains": ["*.example.test"], "max_results": 5},
+            },
+        ),
+        "wider scope",
+    )
+
+    mismatch = harness.request_capability({"capability": "web.search", "scope": {}})
+    _assert_raises(
+        lambda: harness.grant_capability(
+            str(mismatch["request_id"]),
+            {
+                "capability": "web.fetch",
+                "token_ref": "approved:web.fetch",
+                "expires_at": 4_102_444_800.0,
+                "scope": {},
+            },
+        ),
+        "web.fetch",
+    )
+
+    denial = harness.deny_capability(
+        request_id,
+        {
+            "answer": "Approve",
+            "approved": True,
+            "granted": True,
+            "lease": {"capability": "web.search", "token_ref": "secret-ref://lease"},
+            "token_ref": "secret-ref://lease",
+        },
+    )
+    assert denial["answer"] == "Deny"
+    assert denial["approved"] is False
+    assert denial["granted"] is False
+    assert denial["reason"]
+    assert "lease" not in denial
+    assert "token_ref" not in denial
+
+
+def assert_capability_security_revocation_profile(harness: CapabilityHarness) -> None:
+    """Run the capability revocation conformance smoke matrix."""
+    _admit_profile_lease(
+        harness,
+        capability="web.search",
+        lease_id="lease_revoke_cap",
+        token_ref="token:web.search",
+        issued_at=100.0,
+        scope={"allowed_domains": ["docs.example.test"]},
+    )
+    assert harness.token_for("web.search", now=200.0) == "token:web.search"
+    assert harness.valid_lease("web.search", {"allowed_domains": ["docs.example.test"]}, now=200.0)
+    harness.revoke_capability({"capability": "web.search"})
+    assert harness.token_for("web.search", now=200.0) is None
+    assert harness.valid_lease("web.search", {"allowed_domains": ["docs.example.test"]}, now=200.0) is None
+
+    _admit_profile_lease(
+        harness,
+        capability="web.fetch",
+        lease_id="lease_revoke_id",
+        token_ref="token:web.fetch",
+        issued_at=200.0,
+    )
+    _admit_profile_lease(
+        harness,
+        capability="web.context",
+        lease_id="lease_revoke_other",
+        token_ref="token:web.context",
+        issued_at=200.0,
+    )
+    harness.revoke_capability({"lease_id": "lease_revoke_id"})
+    assert harness.token_for("web.fetch", now=300.0) is None
+    assert harness.token_for("web.context", now=300.0) == "token:web.context"
+
+    _admit_profile_lease(
+        harness,
+        capability="cap.old",
+        lease_id="lease_old",
+        token_ref="token:old",
+        issued_at=100.0,
+    )
+    _admit_profile_lease(
+        harness,
+        capability="cap.new",
+        lease_id="lease_new",
+        token_ref="token:new",
+        issued_at=200.0,
+    )
+    harness.revoke_capability({"before": 150.0})
+    assert harness.token_for("cap.old", now=300.0) is None
+    assert harness.token_for("cap.new", now=300.0) == "token:new"
+    harness.revoke_capability({"before": 50.0})
+    assert harness.export_revocations()["revoked_before"] == 150.0
+
+    _admit_profile_lease(
+        harness,
+        capability="cap.persist",
+        lease_id="lease_persist",
+        token_ref="token:persist",
+        issued_at=200.0,
+    )
+    harness.revoke_capability({"capability": "cap.persist", "lease_id": "lease_extra"})
+    exported = harness.export_revocations()
+    assert "cap.persist" in exported["revoked_capabilities"]
+    assert "lease_extra" in exported["revoked_lease_ids"]
+    assert harness.import_revocations(exported) == exported
+
+    _admit_profile_lease(
+        harness,
+        capability="cap.star",
+        lease_id="lease_star",
+        token_ref="token:star",
+        issued_at=200.0,
+    )
+    wildcard = harness.revoke_capability({"capability": "*"})
+    assert wildcard["capabilities"] == ["*"]
+    assert harness.token_for("cap.star", now=300.0) is None
+
+
+def _admit_profile_lease(
+    harness: CapabilityHarness,
+    *,
+    capability: str,
+    lease_id: str,
+    token_ref: str,
+    issued_at: float,
+    scope: dict[str, Any] | None = None,
+    durable: bool = False,
+) -> dict[str, Any]:
+    request = harness.request_capability({"capability": capability, "scope": scope or {}})
+    return harness.grant_capability(
+        str(request["request_id"]),
+        {
+            "lease_id": lease_id,
+            "capability": capability,
+            "token_ref": token_ref,
+            "expires_at": 4_102_444_800.0,
+            "issued_at": issued_at,
+            "durable": durable,
+            "scope": scope or {},
+        },
+    )
+
+
+def _assert_raises(operation: Callable[[], Any], message: str) -> None:
+    try:
+        operation()
+    except Exception as exc:
+        if message not in str(exc):
+            raise AssertionError(f"expected error containing {message!r}, got {exc!r}") from exc
+        return
+    raise AssertionError(f"expected error containing {message!r}")

monoid_agent_kernel/conformance/profiles/control_plane.py

@@ -0,0 +1,41 @@
+"""Control-plane profile metadata."""
+
+from __future__ import annotations
+
+from monoid_agent_kernel.conformance.harness import ControlPlaneHarness
+
+from ._metadata import ProfileMetadata
+
+PROFILE = ProfileMetadata(
+    profile_id="control-plane",
+    title="Control Plane",
+    summary="Backend with external control commands, audit events, lifecycle policy, and stable results.",
+    rule_ids=(
+        "OR-03-LEASE-ADMISSION",
+        "OR-05-EVENT-SEQUENCING",
+        "OR-06-CONTROL-AUDIT",
+        "OR-07-DURABLE-METADATA",
+    ),
+    harnesses=("control-plane",),
+)
+
+
+def assert_control_plane_decision_profile(harness: ControlPlaneHarness) -> None:
+    """Run the approve/deny control decision smoke matrix."""
+    result = harness.run_control_decision_case()
+    assert result["approve_delivered"] is True
+    assert result["deny_delivered"] is True
+    assert result["denied_result_sanitized"] is True
+    assert result["approve_audit_recorded"] is True
+    assert result["deny_audit_recorded"] is True
+
+
+def assert_control_plane_audit_sequence_profile(harness: ControlPlaneHarness) -> None:
+    """Run the control audit sequencing smoke matrix."""
+    result = harness.run_control_audit_sequence_case()
+    assert result["authorized_completed"] is True
+    assert result["failed_audit_recorded"] is True
+    assert result["unauthorized_excluded"] is True
+    assert result["terminal_audit_appended"] is True
+    assert result["sequence_monotonic"] is True
+    assert result["secrets_redacted"] is True

monoid_agent_kernel/conformance/profiles/durable_runner.py

@@ -0,0 +1,42 @@
+"""Durable runner profile metadata."""
+
+from __future__ import annotations
+
+from monoid_agent_kernel.conformance.harness import DurableRunnerHarness
+
+from ._metadata import ProfileMetadata
+
+PROFILE = ProfileMetadata(
+    profile_id="durable-runner",
+    title="Durable Runner",
+    summary="Backend that preserves run state, event sequence, diagnostics, and recovery metadata.",
+    rule_ids=("OR-05-EVENT-SEQUENCING", "OR-07-DURABLE-METADATA", "OR-09-SUBAGENT-BOUNDARY"),
+    harnesses=("durable-runner",),
+)
+
+
+def assert_durable_runner_event_sequence_profile(harness: DurableRunnerHarness) -> None:
+    """Run the event sequence and diagnostics smoke matrix."""
+    result = harness.run_event_sequence_case()
+    assert result["sequence_monotonic"] is True
+    assert result["control_completed"] is True
+    assert result["diagnostics_latest_seq_projected"] is True
+
+
+def assert_durable_runner_recovery_metadata_profile(harness: DurableRunnerHarness) -> None:
+    """Run the recovery metadata smoke matrix."""
+    result = harness.run_recovery_metadata_case()
+    assert result["same_restart_resumed"] is True
+    assert result["same_runtime_config_recovered"] is True
+    assert result["empty_restart_resumed"] is True
+    assert result["empty_runtime_config_recovered"] is True
+
+
+def assert_durable_runner_subagent_diagnostics_profile(harness: DurableRunnerHarness) -> None:
+    """Run the subagent diagnostics projection smoke matrix."""
+    result = harness.run_subagent_diagnostics_case()
+    assert result["diagnostics_summary_present"] is True
+    assert result["identity_projected"] is True
+    assert result["trace_linked"] is True
+    assert result["status_completed"] is True
+    assert result["usage_rollup_matches"] is True

monoid_agent_kernel/conformance/profiles/message_fabric.py

@@ -0,0 +1,42 @@
+"""External agent message-fabric profile metadata and assertions."""
+
+from __future__ import annotations
+
+from monoid_agent_kernel.conformance.harness import MessageFabricHarness
+
+from ._metadata import ProfileMetadata
+
+PROFILE = ProfileMetadata(
+    profile_id="message-fabric",
+    title="Message Fabric",
+    summary="Agent integration that exchanges external-agent messages through durable inbox/outbox envelopes.",
+    rule_ids=("OR-13-EXTERNAL-AGENT-ENVELOPE",),
+    harnesses=("message-fabric",),
+)
+
+
+def assert_message_fabric_profile(harness: MessageFabricHarness) -> None:
+    """Run the external-agent envelope and durable message-fabric smoke matrix."""
+
+    two_peer = harness.run_two_peer_exchange_case()
+    assert two_peer["planner_dispatched"] is True
+    assert two_peer["worker_replied"] is True
+    assert two_peer["planner_trace_preserved"] is True
+    assert two_peer["worker_trace_preserved"] is True
+
+    malformed = harness.run_malformed_envelope_case()
+    assert malformed["status"] == "rejected"
+    assert malformed["error_code"] == "external_agent_envelope_invalid"
+
+    duplicate = harness.run_duplicate_after_restart_case()
+    assert duplicate["first_status"] == "queued"
+    assert duplicate["duplicate_status_after_restart"] == "duplicate"
+    assert duplicate["message_id"] in duplicate["seen_inbox_ids_after_restart"]
+
+    unavailable = harness.run_peer_unavailable_case()
+    assert unavailable["pending"] is True
+    assert unavailable["status"] == "pending"
+    assert unavailable["attempts"] >= 1
+
+
+__all__ = ["PROFILE", "assert_message_fabric_profile"]

monoid_agent_kernel/conformance/profiles/minimal_agent.py

@@ -0,0 +1,13 @@
+"""Minimal local agent profile metadata."""
+
+from __future__ import annotations
+
+from ._metadata import ProfileMetadata
+
+PROFILE = ProfileMetadata(
+    profile_id="minimal-agent",
+    title="Minimal Agent",
+    summary="Local loop or chatbot-style integration with basic lifecycle and model adapter behavior.",
+    rule_ids=(),
+    harnesses=("backend",),
+)