agent-lifecycle-kit 1.50.1__py3-none-any.whl

agent_lifecycle/host_protocol/capabilities.py

@@ -0,0 +1,268 @@
+"""Adapter capability manifests derived from host descriptors."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agent_lifecycle.contracts import canonical_digest
+from agent_lifecycle.host_protocol.acp_capability import validate_host_capabilities
+from agent_lifecycle.host_protocol.event_capture import EVENT_CAPTURE_OPERATION, adapter_declares_event_capture, event_capture_declaration
+from agent_lifecycle.host_protocol.validation import REQUIRED_OPERATION_NAMES, validate_adapter_descriptor
+from agent_lifecycle.runner import validate_sandbox_capability
+
+CAPABILITY_MANIFEST_SCHEMA_VERSION = "agent-adapter-capability-manifest.v1"
+CAPABILITY_MANIFEST_VALIDATION_SCHEMA_VERSION = "agent-adapter-capability-manifest-validation.v1"
+
+
+def build_capability_manifest(descriptor: dict[str, Any]) -> dict[str, Any]:
+    """Build a stable capability manifest from an adapter descriptor."""
+
+    model_routing = descriptor.get("modelRouting") if isinstance(descriptor.get("modelRouting"), dict) else {}
+    operations = descriptor.get("operations") if isinstance(descriptor.get("operations"), list) else []
+    promotion = {
+        "verifiedRequiresLiveTestedHostRange": True,
+        "productionPromotionClaimed": False,
+    }
+    live_range = descriptor.get("liveTestedHostRange")
+    if isinstance(live_range, dict):
+        promotion["liveTestedHostRange"] = live_range
+    return {
+        "schemaVersion": CAPABILITY_MANIFEST_SCHEMA_VERSION,
+        "adapterId": descriptor.get("adapterId"),
+        "host": descriptor.get("host"),
+        "maturity": descriptor.get("maturity"),
+        "descriptorDigest": canonical_digest(descriptor),
+        "unsupportedOperationPolicy": descriptor.get("unsupportedOperationPolicy"),
+        "coreSemantics": descriptor.get("coreSemantics"),
+        "capabilities": [_capability_from_operation(item, descriptor) for item in operations if isinstance(item, dict)],
+        "modelRouting": {
+            "profileSupport": model_routing.get("profileSupport"),
+            "attemptRoutePolicy": model_routing.get("attemptRoutePolicy"),
+            "usageReceiptRequired": model_routing.get("usageReceiptRequired"),
+            "unsupportedClassPolicy": model_routing.get("unsupportedClassPolicy"),
+            "providerModelNamesInCore": model_routing.get("providerModelNamesInCore"),
+            "liveVerified": model_routing.get("liveVerified"),
+        },
+        "runtimeBoundary": {
+            "hostSpecificCode": "adapter-owned",
+            "lifecycleSemantics": descriptor.get("coreSemantics"),
+            "unsupportedOperations": descriptor.get("unsupportedOperationPolicy"),
+            "providerModelNamesInCore": model_routing.get("providerModelNamesInCore"),
+        },
+        "hostCapabilities": _host_capabilities_from_descriptor(descriptor),
+        "sandboxCapabilities": _sandbox_capabilities_from_descriptor(descriptor),
+        "eventCapture": _event_capture_from_descriptor(descriptor),
+        "promotion": promotion,
+    }
+
+
+def validate_capability_manifest(manifest: dict[str, Any], *, descriptor: dict[str, Any]) -> dict[str, Any]:
+    """Validate that a capability manifest still matches its descriptor."""
+
+    blockers: list[dict[str, Any]] = []
+    descriptor_validation = validate_adapter_descriptor(descriptor)
+    if descriptor_validation["status"] == "FAIL":
+        blockers.append(
+            {
+                "code": "adapter-descriptor-invalid",
+                "message": "capability manifest cannot pass while descriptor validation fails",
+                "descriptorBlockers": descriptor_validation["blockers"],
+            }
+        )
+    if manifest.get("schemaVersion") != CAPABILITY_MANIFEST_SCHEMA_VERSION:
+        blockers.append({"code": "invalid-capability-manifest-schema", "message": "unsupported capability manifest schemaVersion"})
+    for key in ("adapterId", "host", "maturity", "unsupportedOperationPolicy", "coreSemantics"):
+        if manifest.get(key) != descriptor.get(key):
+            blockers.append(
+                {
+                    "code": "capability-manifest-descriptor-mismatch",
+                    "field": key,
+                    "expected": descriptor.get(key),
+                    "actual": manifest.get(key),
+                }
+            )
+    expected_digest = canonical_digest(descriptor)
+    if manifest.get("descriptorDigest") != expected_digest:
+        blockers.append(
+            {
+                "code": "capability-manifest-descriptor-digest-mismatch",
+                "expected": expected_digest,
+                "actual": manifest.get("descriptorDigest"),
+            }
+        )
+    _validate_manifest_capabilities(manifest, descriptor, blockers)
+    _validate_runtime_boundary(manifest, descriptor, blockers)
+    _validate_host_capability_drift(manifest, descriptor, blockers)
+    _validate_sandbox_capability_drift(manifest, descriptor, blockers)
+    _validate_event_capture(manifest, descriptor, blockers)
+    status = "PASS" if not blockers else "FAIL"
+    return {
+        "schemaVersion": CAPABILITY_MANIFEST_VALIDATION_SCHEMA_VERSION,
+        "status": status,
+        "adapterId": descriptor.get("adapterId"),
+        "host": descriptor.get("host"),
+        "maturity": descriptor.get("maturity"),
+        "capabilityCount": len(manifest.get("capabilities", [])) if isinstance(manifest.get("capabilities"), list) else 0,
+        "blockers": blockers,
+    }
+
+
+def _capability_from_operation(operation: dict[str, Any], descriptor: dict[str, Any]) -> dict[str, Any]:
+    offline_conformance = operation.get("offlineConformance")
+    return {
+        "name": operation.get("name"),
+        "mapping": operation.get("mapping"),
+        "offlineConformance": offline_conformance,
+        "support": "declared",
+        "unsupportedOperationPolicy": descriptor.get("unsupportedOperationPolicy"),
+        "lifecycleSemantics": descriptor.get("coreSemantics"),
+        "liveEvidenceRequiredForVerified": offline_conformance != "deterministic",
+    }
+
+
+def _event_capture_from_descriptor(descriptor: dict[str, Any]) -> dict[str, Any]:
+    if adapter_declares_event_capture(descriptor=descriptor):
+        return event_capture_declaration()
+    return {
+        "status": "NOT_DECLARED",
+        "portableEventSchema": "agent-adapter-event.v1",
+        "categories": [],
+        "producerBoundary": None,
+        "promotionRequired": False,
+    }
+
+
+def _host_capabilities_from_descriptor(descriptor: dict[str, Any]) -> list[dict[str, Any]]:
+    capabilities = descriptor.get("hostCapabilities")
+    if not isinstance(capabilities, list):
+        return []
+    return [dict(item) for item in capabilities if isinstance(item, dict)]
+
+
+def _sandbox_capabilities_from_descriptor(descriptor: dict[str, Any]) -> dict[str, Any] | None:
+    capabilities = descriptor.get("sandboxCapabilities")
+    if not isinstance(capabilities, dict):
+        return None
+    return dict(capabilities)
+
+
+def _validate_manifest_capabilities(
+    manifest: dict[str, Any],
+    descriptor: dict[str, Any],
+    blockers: list[dict[str, Any]],
+) -> None:
+    capabilities = manifest.get("capabilities")
+    if not isinstance(capabilities, list):
+        blockers.append({"code": "invalid-capability-manifest", "message": "capabilities must be an array"})
+        return
+    descriptor_operations = descriptor.get("operations")
+    if not isinstance(descriptor_operations, list):
+        return
+    descriptor_names = {item.get("name") for item in descriptor_operations if isinstance(item, dict)}
+    manifest_names = {item.get("name") for item in capabilities if isinstance(item, dict)}
+    missing_required = sorted(REQUIRED_OPERATION_NAMES.difference(manifest_names))
+    extra = sorted(manifest_names.difference(descriptor_names))
+    missing_descriptor = sorted(descriptor_names.difference(manifest_names))
+    if missing_required:
+        blockers.append({"code": "capability-required-operation-missing", "operations": missing_required})
+    if missing_descriptor or extra:
+        blockers.append(
+            {
+                "code": "capability-manifest-operation-drift",
+                "missingFromManifest": missing_descriptor,
+                "extraInManifest": extra,
+            }
+        )
+    for item in capabilities:
+        if not isinstance(item, dict):
+            blockers.append({"code": "invalid-capability-entry", "message": "capability entries must be objects"})
+            continue
+        if item.get("unsupportedOperationPolicy") != "fail-closed":
+            blockers.append({"code": "capability-unsupported-operation-policy", "capability": item.get("name")})
+        if item.get("lifecycleSemantics") != "delegated-to-agent-lifecycle-core":
+            blockers.append({"code": "capability-core-semantics-overclaim", "capability": item.get("name")})
+
+
+def _validate_runtime_boundary(
+    manifest: dict[str, Any],
+    descriptor: dict[str, Any],
+    blockers: list[dict[str, Any]],
+) -> None:
+    boundary = manifest.get("runtimeBoundary")
+    if not isinstance(boundary, dict):
+        blockers.append({"code": "capability-runtime-boundary-missing", "message": "runtimeBoundary must be an object"})
+        return
+    if boundary.get("lifecycleSemantics") != descriptor.get("coreSemantics"):
+        blockers.append({"code": "capability-runtime-boundary-drift", "field": "lifecycleSemantics"})
+    if boundary.get("unsupportedOperations") != "fail-closed":
+        blockers.append({"code": "capability-runtime-boundary-policy", "field": "unsupportedOperations"})
+    if boundary.get("providerModelNamesInCore") is not False:
+        blockers.append({"code": "capability-provider-model-boundary", "message": "provider model names must stay out of core contracts"})
+
+
+def _validate_host_capability_drift(
+    manifest: dict[str, Any],
+    descriptor: dict[str, Any],
+    blockers: list[dict[str, Any]],
+) -> None:
+    descriptor_capabilities = descriptor.get("hostCapabilities")
+    manifest_capabilities = manifest.get("hostCapabilities")
+    if descriptor_capabilities is None and manifest_capabilities is None:
+        return
+    if not isinstance(descriptor_capabilities, list):
+        descriptor_capabilities = []
+    if manifest_capabilities != descriptor_capabilities:
+        blockers.append({"code": "capability-manifest-host-capability-drift"})
+        return
+    validation = validate_host_capabilities(
+        manifest_capabilities,
+        adapter_id=descriptor.get("adapterId") if isinstance(descriptor.get("adapterId"), str) else None,
+        host=descriptor.get("host") if isinstance(descriptor.get("host"), str) else None,
+    )
+    if validation["status"] == "FAIL":
+        blockers.append({"code": "capability-manifest-host-capability-invalid", "blockers": validation["blockers"]})
+
+
+def _validate_sandbox_capability_drift(
+    manifest: dict[str, Any],
+    descriptor: dict[str, Any],
+    blockers: list[dict[str, Any]],
+) -> None:
+    descriptor_capability = descriptor.get("sandboxCapabilities")
+    manifest_capability = manifest.get("sandboxCapabilities")
+    if descriptor_capability is None and manifest_capability is None:
+        return
+    if manifest_capability != descriptor_capability:
+        blockers.append({"code": "capability-manifest-sandbox-capability-drift"})
+        return
+    if not isinstance(manifest_capability, dict):
+        blockers.append({"code": "capability-manifest-sandbox-capability-invalid"})
+        return
+    validation = validate_sandbox_capability(manifest_capability)
+    if validation["status"] == "FAIL":
+        blockers.append({"code": "capability-manifest-sandbox-capability-invalid", "blockers": validation["blockers"]})
+
+
+def _validate_event_capture(
+    manifest: dict[str, Any],
+    descriptor: dict[str, Any],
+    blockers: list[dict[str, Any]],
+) -> None:
+    capture = manifest.get("eventCapture")
+    if not isinstance(capture, dict):
+        blockers.append({"code": "capability-event-capture-missing", "message": "eventCapture must be an object"})
+        return
+    expected_declared = adapter_declares_event_capture(descriptor=descriptor)
+    actual_declared = capture.get("status") == "DECLARED"
+    if actual_declared != expected_declared:
+        blockers.append({"code": "capability-event-capture-drift", "expectedDeclared": expected_declared, "actualStatus": capture.get("status")})
+    if actual_declared:
+        operations = descriptor.get("operations", [])
+        if not any(isinstance(item, dict) and item.get("name") == EVENT_CAPTURE_OPERATION for item in operations):
+            blockers.append({"code": "capability-event-capture-operation-missing", "operation": EVENT_CAPTURE_OPERATION})
+        if capture.get("portableEventSchema") != "agent-adapter-event.v1":
+            blockers.append({"code": "capability-event-capture-schema", "message": "event capture must use agent-adapter-event.v1"})
+        if capture.get("producerBoundary") != "adapter-owned":
+            blockers.append({"code": "capability-event-capture-boundary", "message": "event producer boundary must be adapter-owned"})
+    if capture.get("promotionRequired") is not False:
+        blockers.append({"code": "capability-event-capture-promotion-overclaim", "message": "event capture declaration must not imply promotion"})

agent_lifecycle/host_protocol/contracts.py

@@ -0,0 +1,214 @@
+"""Closed host-operation envelopes used by adapters."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from agent_lifecycle.contracts.errors import LifecycleError
+
+HostOperationStatus = Literal["PASS", "FAIL", "BLOCKED"]
+HostAdapterEventStatus = Literal["INFO", "PASS", "FAIL", "BLOCKED"]
+HostAdapterEventType = Literal[
+    "session.started",
+    "task.launched",
+    "command.completed",
+    "writes.summarized",
+    "usage.reported",
+    "task.blocked",
+    "task.completed",
+]
+
+
+def _reject_unknown(value: dict[str, Any], allowed: set[str], label: str) -> None:
+    unknown = sorted(set(value).difference(allowed))
+    if unknown:
+        raise LifecycleError("unknown-field", f"{label}: unknown fields: {', '.join(unknown)}")
+
+
+@dataclass(frozen=True, slots=True)
+class HostOperationRequest:
+    operation_id: str
+    capability: str
+    inputs: dict[str, Any] = field(default_factory=dict)
+    outputs: list[dict[str, Any]] = field(default_factory=list)
+    constraints: dict[str, Any] = field(default_factory=dict)
+    model_route: dict[str, Any] | None = None
+
+    schema_version = "agent-host-operation-request.v1"
+
+    def to_json(self) -> dict[str, Any]:
+        payload = {
+            "schemaVersion": self.schema_version,
+            "operationId": self.operation_id,
+            "capability": self.capability,
+            "inputs": self.inputs,
+            "outputs": self.outputs,
+            "constraints": self.constraints,
+        }
+        if self.model_route is not None:
+            payload["modelRoute"] = self.model_route
+        return payload
+
+    @classmethod
+    def from_json(cls, value: dict[str, Any]) -> "HostOperationRequest":
+        allowed = {"schemaVersion", "operationId", "capability", "inputs", "outputs", "constraints", "modelRoute"}
+        _reject_unknown(value, allowed, "host operation request")
+        if value.get("schemaVersion") != cls.schema_version:
+            raise LifecycleError("unsupported-schema", "host operation request schemaVersion is unsupported")
+        if not isinstance(value.get("operationId"), str) or not value["operationId"]:
+            raise LifecycleError("invalid-host-operation", "operationId is required")
+        if not isinstance(value.get("capability"), str) or not value["capability"]:
+            raise LifecycleError("invalid-host-operation", "capability is required")
+        if not isinstance(value.get("inputs"), dict):
+            raise LifecycleError("invalid-host-operation", "inputs must be an object")
+        if not isinstance(value.get("outputs"), list):
+            raise LifecycleError("invalid-host-operation", "outputs must be an array")
+        if not isinstance(value.get("constraints"), dict):
+            raise LifecycleError("invalid-host-operation", "constraints must be an object")
+        model_route = value.get("modelRoute")
+        if model_route is not None and not isinstance(model_route, dict):
+            raise LifecycleError("invalid-host-operation", "modelRoute must be an object")
+        return cls(
+            operation_id=value["operationId"],
+            capability=value["capability"],
+            inputs=value["inputs"],
+            outputs=value["outputs"],
+            constraints=value["constraints"],
+            model_route=model_route,
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class HostOperationReceipt:
+    operation_id: str
+    capability: str
+    status: HostOperationStatus
+    outputs: list[dict[str, Any]] = field(default_factory=list)
+    usage: dict[str, Any] = field(default_factory=dict)
+
+    schema_version = "agent-host-operation-receipt.v1"
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "schemaVersion": self.schema_version,
+            "operationId": self.operation_id,
+            "capability": self.capability,
+            "status": self.status,
+            "outputs": self.outputs,
+            "usage": self.usage,
+        }
+
+    @classmethod
+    def from_json(cls, value: dict[str, Any]) -> "HostOperationReceipt":
+        allowed = {"schemaVersion", "operationId", "capability", "status", "outputs", "usage"}
+        _reject_unknown(value, allowed, "host operation receipt")
+        if value.get("schemaVersion") != cls.schema_version:
+            raise LifecycleError("unsupported-schema", "host operation receipt schemaVersion is unsupported")
+        status = value.get("status")
+        if status not in {"PASS", "FAIL", "BLOCKED"}:
+            raise LifecycleError("invalid-host-operation", "status is unsupported")
+        if not isinstance(value.get("operationId"), str) or not value["operationId"]:
+            raise LifecycleError("invalid-host-operation", "operationId is required")
+        if not isinstance(value.get("capability"), str) or not value["capability"]:
+            raise LifecycleError("invalid-host-operation", "capability is required")
+        if not isinstance(value.get("outputs"), list):
+            raise LifecycleError("invalid-host-operation", "outputs must be an array")
+        if not isinstance(value.get("usage"), dict):
+            raise LifecycleError("invalid-host-operation", "usage must be an object")
+        return cls(
+            operation_id=value["operationId"],
+            capability=value["capability"],
+            status=status,
+            outputs=value["outputs"],
+            usage=value["usage"],
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class HostAdapterEvent:
+    event_id: str
+    host: str
+    adapter_id: str
+    run_id: str
+    task_id: str
+    operation_id: str
+    sequence: int
+    event_type: HostAdapterEventType
+    status: HostAdapterEventStatus
+    recorded_at: str
+    payload: dict[str, Any] = field(default_factory=dict)
+
+    schema_version = "agent-adapter-event.v1"
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "schemaVersion": self.schema_version,
+            "eventId": self.event_id,
+            "host": self.host,
+            "adapterId": self.adapter_id,
+            "runId": self.run_id,
+            "taskId": self.task_id,
+            "operationId": self.operation_id,
+            "sequence": self.sequence,
+            "eventType": self.event_type,
+            "status": self.status,
+            "recordedAt": self.recorded_at,
+            "payload": self.payload,
+        }
+
+    @classmethod
+    def from_json(cls, value: dict[str, Any]) -> "HostAdapterEvent":
+        allowed = {
+            "schemaVersion",
+            "eventId",
+            "host",
+            "adapterId",
+            "runId",
+            "taskId",
+            "operationId",
+            "sequence",
+            "eventType",
+            "status",
+            "recordedAt",
+            "payload",
+        }
+        _reject_unknown(value, allowed, "adapter event")
+        if value.get("schemaVersion") != cls.schema_version:
+            raise LifecycleError("unsupported-schema", "adapter event schemaVersion is unsupported")
+        for key in ("eventId", "host", "adapterId", "runId", "taskId", "operationId", "recordedAt"):
+            if not isinstance(value.get(key), str) or not value[key]:
+                raise LifecycleError("invalid-adapter-event", f"{key} is required")
+        sequence = value.get("sequence")
+        if not isinstance(sequence, int) or isinstance(sequence, bool) or sequence < 1:
+            raise LifecycleError("invalid-adapter-event", "sequence must be a positive integer")
+        event_type = value.get("eventType")
+        if event_type not in {
+            "session.started",
+            "task.launched",
+            "command.completed",
+            "writes.summarized",
+            "usage.reported",
+            "task.blocked",
+            "task.completed",
+        }:
+            raise LifecycleError("invalid-adapter-event", "eventType is unsupported")
+        status = value.get("status")
+        if status not in {"INFO", "PASS", "FAIL", "BLOCKED"}:
+            raise LifecycleError("invalid-adapter-event", "status is unsupported")
+        payload = value.get("payload")
+        if not isinstance(payload, dict):
+            raise LifecycleError("invalid-adapter-event", "payload must be an object")
+        return cls(
+            event_id=value["eventId"],
+            host=value["host"],
+            adapter_id=value["adapterId"],
+            run_id=value["runId"],
+            task_id=value["taskId"],
+            operation_id=value["operationId"],
+            sequence=sequence,
+            event_type=event_type,
+            status=status,
+            recorded_at=value["recordedAt"],
+            payload=payload,
+        )