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

monoid_agent_kernel/conformance/profiles/multi_agent.py

@@ -0,0 +1,112 @@
+"""Multi-agent profile metadata."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from monoid_agent_kernel.conformance.harness import CapabilityHarness, MultiAgentBackendHarness
+
+from ._metadata import ProfileMetadata
+
+PROFILE = ProfileMetadata(
+    profile_id="multi-agent",
+    title="Multi Agent",
+    summary="Subagent runtime with identity, capability isolation, shared revocation, and trace linkage.",
+    rule_ids=("OR-04-REVOCATION-SCOPE", "OR-09-SUBAGENT-BOUNDARY"),
+    harnesses=("multi-agent-backend", "capability"),
+)
+
+
+def assert_multi_agent_backend_boundary_profile(harness: MultiAgentBackendHarness) -> None:
+    """Run the backend subagent identity and diagnostics smoke matrix."""
+    result = harness.run_subagent_boundary_case()
+    assert result["parent_stream_isolated"] is True
+    assert result["child_identity_valid"] is True
+    assert result["descendant_events_readable"] is True
+    assert result["non_descendant_rejected"] is True
+    assert result["path_traversal_rejected"] is True
+    assert result["trace_linked"] is True
+    assert result["task_result_linked"] is True
+    assert result["diagnostics_summary_present"] is True
+    assert result["usage_rollup_matches"] is True
+
+
+def assert_multi_agent_backend_capability_boundary_profile(harness: MultiAgentBackendHarness) -> None:
+    """Run the child capability-boundary smoke matrix."""
+    result = harness.run_subagent_capability_boundary_case()
+    assert result["revoked_event_observed"] is True
+    assert result["child_result_observed_revoked"] is True
+    assert result["gated_handler_not_called"] is True
+
+
+def assert_multi_agent_shared_revocation_profile(harness: CapabilityHarness) -> None:
+    """Run the child-vault revocation sharing smoke matrix."""
+    _admit_profile_lease(
+        harness,
+        capability="web.search",
+        lease_id="lease_parent_live",
+        token_ref="token:parent-live",
+        durable=False,
+    )
+    _admit_profile_lease(
+        harness,
+        capability="web.fetch",
+        lease_id="lease_parent_durable",
+        token_ref="token:parent-durable",
+        durable=True,
+    )
+
+    child = harness.fork_child()
+    assert child.token_for("web.search", now=200.0) is None
+    assert child.token_for("web.fetch", now=200.0) == "token:parent-durable"
+
+    _admit_profile_lease(
+        child,
+        capability="web.search",
+        lease_id="lease_child_live",
+        token_ref="token:child-live",
+        durable=False,
+    )
+    assert harness.token_for("web.search", now=200.0) == "token:parent-live"
+    assert child.token_for("web.search", now=200.0) == "token:child-live"
+
+    harness.revoke_capability({"capability": "web.search"})
+    assert harness.token_for("web.search", now=200.0) is None
+    assert child.token_for("web.search", now=200.0) is None
+
+    _admit_profile_lease(
+        child,
+        capability="web.context",
+        lease_id="lease_child_only",
+        token_ref="token:child-only",
+        durable=False,
+    )
+    assert child.token_for("web.context", now=200.0) == "token:child-only"
+    assert harness.token_for("web.context", now=200.0) is None
+
+    child.revoke_capability({"capability": "*"})
+    assert harness.token_for("web.fetch", now=200.0) is None
+    assert child.token_for("web.context", now=200.0) is None
+
+
+def _admit_profile_lease(
+    harness: CapabilityHarness,
+    *,
+    capability: str,
+    lease_id: str,
+    token_ref: str,
+    durable: bool,
+) -> dict[str, Any]:
+    request = harness.request_capability({"capability": capability, "scope": {}})
+    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": 100.0,
+            "durable": durable,
+            "scope": {},
+        },
+    )

monoid_agent_kernel/conformance/profiles/provider_gateway.py

@@ -0,0 +1,107 @@
+"""Provider-gateway profile metadata."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from monoid_agent_kernel.conformance.harness import GatewayHarness
+
+from ._metadata import ProfileMetadata
+
+PROFILE = ProfileMetadata(
+    profile_id="provider-gateway",
+    title="Provider Gateway",
+    summary="Gateway runtime with signed scopes, domain boundaries, redirect checks, and effective caps.",
+    rule_ids=("OR-01-SCOPE-RELATION", "OR-02-CAPABILITY-BOUNDARY", "OR-08-PROVIDER-CAPS"),
+    harnesses=("gateway",),
+)
+
+
+def assert_provider_gateway_profile(harness: GatewayHarness) -> None:
+    """Run the provider-gateway conformance smoke matrix."""
+    search = harness.call_gateway(
+        "web.search",
+        {"query": "binding"},
+        signed_scope={
+            "binding_id": "search_docs",
+            "max_calls": 2,
+            "max_results": 1,
+            "allowed_domains": ["docs.example.test"],
+            "blocked_domains": ["blog.example.test"],
+        },
+    )
+    assert search["effective_max_results"] == 1
+    assert search["result_count"] == 1
+    assert {result["domain"] for result in search["results"]} == {"docs.example.test"}
+
+    narrowed = harness.call_gateway(
+        "web.search",
+        {"binding_id": "search_docs", "query": "binding", "max_results": 1},
+        signed_scope={
+            "binding_id": "search_docs",
+            "max_calls": 2,
+            "max_results": 3,
+            "allowed_domains": ["*.example.test"],
+        },
+    )
+    assert narrowed["effective_max_results"] == 1
+
+    _assert_raises(
+        lambda: harness.call_gateway(
+            "web.search",
+            {"binding_id": "search_docs", "query": "binding", "max_results": 2},
+            signed_scope={"binding_id": "search_docs", "max_calls": 2, "max_results": 1},
+        ),
+        "max_results exceeds signed token scope",
+    )
+    _assert_raises(
+        lambda: harness.call_gateway(
+            "web.fetch",
+            {"url": "https://docs.example.test/monoid-agent-kernel/web"},
+            signed_capability="web.search",
+            signed_scope={"binding_id": "search_docs", "allowed_domains": ["docs.example.test"]},
+        ),
+        "capability does not match endpoint",
+    )
+
+    fetched = harness.call_gateway(
+        "web.fetch",
+        {"url": "https://docs.example.test/monoid-agent-kernel/web"},
+        signed_scope={
+            "binding_id": "fetch_docs",
+            "max_calls": 2,
+            "max_bytes": 12,
+            "timeout_s": 2,
+            "allowed_domains": ["docs.example.test"],
+        },
+    )
+    assert fetched["effective_max_bytes"] == 12
+    assert fetched["effective_timeout_s"] == 2
+    assert fetched["content_bytes"] <= 12
+
+    context = harness.call_gateway(
+        "web.context",
+        {"query": "binding"},
+        signed_scope={
+            "binding_id": "context_docs",
+            "max_calls": 2,
+            "max_tokens": 2,
+            "max_urls": 1,
+            "max_snippets": 1,
+            "allowed_domains": ["docs.example.test"],
+        },
+    )
+    assert context["effective_max_tokens"] == 2
+    assert context["effective_max_urls"] == 1
+    assert context["effective_max_snippets"] == 1
+
+
+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/reference_full.py

@@ -0,0 +1,135 @@
+"""Reference-full profile metadata."""
+
+from __future__ import annotations
+
+from typing import Protocol
+from typing import Any, Callable
+
+from monoid_agent_kernel.conformance.harness import (
+    BackendHarness,
+    CapabilityHarness,
+    ControlPlaneHarness,
+    DurableRunnerHarness,
+    GatewayHarness,
+    MessageFabricHarness,
+    MultiAgentBackendHarness,
+    SideEffectHarness,
+    ToolAgentHarness,
+)
+
+from .capability_security import (
+    assert_capability_security_lease_admission,
+    assert_capability_security_revocation_profile,
+)
+from .control_plane import (
+    assert_control_plane_audit_sequence_profile,
+    assert_control_plane_decision_profile,
+)
+from .durable_runner import (
+    assert_durable_runner_event_sequence_profile,
+    assert_durable_runner_recovery_metadata_profile,
+    assert_durable_runner_subagent_diagnostics_profile,
+)
+from ._metadata import ProfileMetadata
+from .message_fabric import assert_message_fabric_profile
+from .multi_agent import (
+    assert_multi_agent_backend_boundary_profile,
+    assert_multi_agent_backend_capability_boundary_profile,
+    assert_multi_agent_shared_revocation_profile,
+)
+from .provider_gateway import assert_provider_gateway_profile
+from .side_effect_tool_agent import assert_side_effect_tool_agent_profile
+from .tool_agent import (
+    assert_tool_agent_generic_ask_approval_profile,
+    assert_tool_agent_surface_admission_profile,
+)
+
+PROFILE = ProfileMetadata(
+    profile_id="reference-full",
+    title="Reference Full",
+    summary="Bundled Reference services and Studio smoke path across current operational rules.",
+    rule_ids=(
+        "OR-01-SCOPE-RELATION",
+        "OR-02-CAPABILITY-BOUNDARY",
+        "OR-03-LEASE-ADMISSION",
+        "OR-04-REVOCATION-SCOPE",
+        "OR-05-EVENT-SEQUENCING",
+        "OR-06-CONTROL-AUDIT",
+        "OR-07-DURABLE-METADATA",
+        "OR-08-PROVIDER-CAPS",
+        "OR-09-SUBAGENT-BOUNDARY",
+        "OR-10-TOOL-SURFACE-ADMISSION",
+        "OR-11-GENERIC-ASK-APPROVAL",
+        "OR-12-DURABLE-SIDE-EFFECT",
+        "OR-13-EXTERNAL-AGENT-ENVELOPE",
+    ),
+    harnesses=("backend", "capability", "gateway", "side-effect", "message-fabric", "studio"),
+)
+
+
+class ReferenceFullFactory(Protocol):
+    def new_backend(self) -> BackendHarness:
+        """Return a fresh Reference backend harness."""
+
+    def new_tool_agent(self) -> ToolAgentHarness:
+        """Return a fresh Reference tool-agent harness."""
+
+    def new_control_plane(self) -> ControlPlaneHarness:
+        """Return a fresh Reference control-plane harness."""
+
+    def new_durable_runner(self) -> DurableRunnerHarness:
+        """Return a fresh Reference durable-runner harness."""
+
+    def new_multi_agent(self) -> MultiAgentBackendHarness:
+        """Return a fresh Reference multi-agent backend harness."""
+
+    def new_side_effect(self) -> SideEffectHarness:
+        """Return a fresh Reference side-effect harness."""
+
+    def new_message_fabric(self) -> MessageFabricHarness:
+        """Return a fresh Reference message-fabric harness."""
+
+    def new_capability(self) -> CapabilityHarness:
+        """Return a fresh Reference capability harness."""
+
+    def new_gateway(self) -> GatewayHarness:
+        """Return a fresh Reference gateway harness."""
+
+    def run_studio_smoke(self) -> dict:
+        """Run the Reference Studio smoke path."""
+
+
+def assert_reference_full_profile(factory: ReferenceFullFactory) -> None:
+    """Run the bundled Reference implementation across the current profile set."""
+    assert_provider_gateway_profile(factory.new_gateway())
+
+    assert_capability_security_lease_admission(factory.new_capability())
+    assert_capability_security_revocation_profile(factory.new_capability())
+    assert_multi_agent_shared_revocation_profile(factory.new_capability())
+
+    _run_with_close(factory.new_control_plane(), assert_control_plane_decision_profile)
+    _run_with_close(factory.new_control_plane(), assert_control_plane_audit_sequence_profile)
+
+    _run_with_close(factory.new_tool_agent(), assert_tool_agent_surface_admission_profile)
+    _run_with_close(factory.new_tool_agent(), assert_tool_agent_generic_ask_approval_profile)
+    _run_with_close(factory.new_side_effect(), assert_side_effect_tool_agent_profile)
+    _run_with_close(factory.new_message_fabric(), assert_message_fabric_profile)
+
+    _run_with_close(factory.new_durable_runner(), assert_durable_runner_event_sequence_profile)
+    _run_with_close(factory.new_durable_runner(), assert_durable_runner_recovery_metadata_profile)
+    _run_with_close(factory.new_durable_runner(), assert_durable_runner_subagent_diagnostics_profile)
+
+    _run_with_close(factory.new_multi_agent(), assert_multi_agent_backend_boundary_profile)
+    _run_with_close(factory.new_multi_agent(), assert_multi_agent_backend_capability_boundary_profile)
+
+    smoke = factory.run_studio_smoke()
+    assert smoke["run_id"]
+
+
+def _run_with_close(harness: Any, assertion: Callable[[Any], None]) -> None:
+    try:
+        assertion(harness)
+    finally:
+        close = getattr(harness, "close", None)
+        if callable(close):
+            close()

monoid_agent_kernel/conformance/profiles/side_effect_tool_agent.py

@@ -0,0 +1,36 @@
+"""External side-effect tool profile metadata and assertions."""
+
+from __future__ import annotations
+
+from monoid_agent_kernel.conformance.harness import SideEffectHarness
+
+from ._metadata import ProfileMetadata
+
+PROFILE = ProfileMetadata(
+    profile_id="side-effect-tool-agent",
+    title="Side-Effect Tool Agent",
+    summary="Agent integration that runs external side-effect tools with durable outbox or idempotency admission.",
+    rule_ids=("OR-12-DURABLE-SIDE-EFFECT",),
+    harnesses=("side-effect",),
+)
+
+
+def assert_side_effect_tool_agent_profile(harness: SideEffectHarness) -> None:
+    """Run the Phase 2 durable side-effect/outbox smoke matrix."""
+
+    dispatched = harness.run_outbox_dispatched_case()
+    assert dispatched["requested"] is True
+    assert dispatched["dispatched"] is True
+
+    pending = harness.run_pending_recovery_case()
+    assert pending["initial_status"] == "pending"
+    assert pending["recovered_status"] == "pending"
+    assert pending["request_id"] == pending["recovered_request_id"]
+
+    rejected = harness.run_strict_rejected_case()
+    assert rejected["denied"] is True
+    assert rejected["handler_finished"] is False
+
+    idempotent = harness.run_idempotent_inline_case()
+    assert idempotent["missing_denied"] is True
+    assert idempotent["valid_finished"] is True

monoid_agent_kernel/conformance/profiles/tool_agent.py

@@ -0,0 +1,39 @@
+"""Tool-using agent profile metadata and assertions."""
+
+from __future__ import annotations
+
+from monoid_agent_kernel.conformance.harness import ToolAgentHarness
+
+from ._metadata import ProfileMetadata
+
+PROFILE = ProfileMetadata(
+    profile_id="tool-agent",
+    title="Tool Agent",
+    summary="Agent integration that executes tools with bindings, permissions, and output validation.",
+    rule_ids=(
+        "OR-10-TOOL-SURFACE-ADMISSION",
+        "OR-11-GENERIC-ASK-APPROVAL",
+    ),
+    harnesses=("tool-agent",),
+)
+
+
+def assert_tool_agent_surface_admission_profile(harness: ToolAgentHarness) -> None:
+    """Run the Phase 2 tool surface admission smoke matrix."""
+    result = harness.run_tool_surface_admission_case()
+    assert result["permission_denied"] is True
+    assert result["denial_code"] == "tool_quota_exceeded"
+    assert result["run_completed"] is True
+
+
+def assert_tool_agent_generic_ask_approval_profile(harness: ToolAgentHarness) -> None:
+    """Run the Phase 2 generic authorization='ask' approval smoke matrix."""
+    result = harness.run_generic_ask_approval_case()
+    assert result["approved_requested"] is True
+    assert result["approved_recorded"] is True
+    assert result["approved_replayed_once"] is True
+    assert result["denied_requested"] is True
+    assert result["denied_recorded"] is True
+    assert result["denied_replayed"] is False
+    assert result["stale_approved_recorded"] is True
+    assert result["stale_replay_rejected"] is True