agentengine-sdk-python 0.8.4__py3-none-any.whl → 0.8.6__py3-none-any.whl

ksadk/a2a/external_transport.py

@@ -244,9 +244,7 @@ class _JSONPayloadLimits:
             if self._in_string:
                 self._string_bytes += 1
                 if self._string_bytes > _MAX_EXTERNAL_JSON_STRING_BYTES:
-                    raise httpx.RemoteProtocolError(
-                        "external A2A JSON string exceeds 1 MiB"
-                    )
+                    raise httpx.RemoteProtocolError("external A2A JSON string exceeds 1 MiB")
                 if self._escaped:
                     self._escaped = False
                 elif byte == ord("\\"):
@@ -421,7 +419,8 @@ class RuntimeLocalA2AExternalTransport(A2AExternalTransport):
             or parsed.password is not None
             or parsed.fragment
             or parsed.netloc.rsplit("@", 1)[-1].endswith(":")
-            or port is not None and not 1 <= port <= 65535
+            or port is not None
+            and not 1 <= port <= 65535
         ):
             raise ValueError("external public A2A route must be an absolute HTTPS URL")
         try:

ksadk/a2a/identity.py

@@ -2,10 +2,13 @@
 
 from __future__ import annotations
 
+import hashlib
 from abc import ABC, abstractmethod
-from dataclasses import dataclass
-from typing import Any, Awaitable, Callable
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Annotated, Any, Awaitable, Callable, Literal, cast
 
+from pydantic import BaseModel, ConfigDict, Field, field_validator
 from starlette.middleware.base import BaseHTTPMiddleware
 from starlette.requests import Request
 from starlette.responses import JSONResponse
@@ -20,6 +23,65 @@ _AUTHN_MODE_BY_CALLER_TYPE = {
     "service": "gateway_service",
 }
 
+A2AAuthnMode = Literal[
+    "platform_api_key",
+    "console_session",
+    "workload_permit",
+    "gateway_service",
+]
+A2A_AUTHN_MODES = frozenset(
+    {
+        "platform_api_key",
+        "console_session",
+        "workload_permit",
+        "gateway_service",
+    }
+)
+
+
+def canonical_a2a_authn_mode(value: str) -> A2AAuthnMode:
+    """Map the legacy Runtime ``api_key`` value to the versioned wire enum."""
+
+    canonical = "platform_api_key" if value == "api_key" else value
+    if canonical not in A2A_AUTHN_MODES:
+        raise ValueError(f"unsupported A2A authentication mode: {value!r}")
+    return cast(A2AAuthnMode, canonical)
+
+
+class A2AApiKeyPrincipal(BaseModel):
+    """Normalized API-key service response; the raw credential is never present."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid", hide_input_in_errors=True)
+
+    key_id: str = Field(min_length=1, max_length=128)
+    account_id: str = Field(min_length=1, max_length=128)
+    sub_account_id: str = Field(min_length=1, max_length=128)
+    principal_id: str = Field(min_length=1, max_length=128)
+    product_scopes: frozenset[
+        Annotated[
+            str,
+            Field(min_length=1, max_length=64, pattern=r"^[A-Z][A-Z0-9_-]*$"),
+        ]
+    ] = Field(min_length=1)
+    expires_at: datetime | None = None
+
+    @field_validator("expires_at")
+    @classmethod
+    def _timezone_required(cls, value: datetime | None) -> datetime | None:
+        if value is not None and value.utcoffset() is None:
+            raise ValueError("expires_at must include a timezone")
+        return value
+
+    @field_validator("product_scopes")
+    @classmethod
+    def _a2a_scope_required(cls, value: frozenset[str]) -> frozenset[str]:
+        if "A2A" not in value:
+            raise ValueError("A2A_API_KEY_SCOPE_DENIED")
+        return value
+
+    def has_required_scope(self, required_scope: Literal["A2A"] = "A2A") -> bool:
+        return required_scope in self.product_scopes
+
 
 @dataclass(frozen=True)
 class A2AIngressTargetBinding:
@@ -32,6 +94,28 @@ class A2AIngressTargetBinding:
     a2a_agent_id: str
 
 
+@dataclass(frozen=True)
+class A2AIngressTaskBinding:
+    """Task provenance from a verified, request-bound Gateway assertion."""
+
+    platform_task_id: str
+    target_version_id: str
+    operation: str
+
+    def validate(self) -> None:
+        if (
+            not self.platform_task_id.startswith("a2a-task-")
+            or len(self.platform_task_id) <= len("a2a-task-")
+            or len(self.platform_task_id) > 64
+            or not self.target_version_id.strip()
+            or len(self.target_version_id) > 64
+            or self.operation not in {
+                "send_message", "get_task", "subscribe_to_task", "cancel_task"
+            }
+        ):
+            raise PermissionError("verified Gateway task binding is invalid")
+
+
 @dataclass(frozen=True)
 class A2AIngressIdentity:
     """Caller identity verified by Gateway mTLS and target-bound forwarding."""
@@ -45,8 +129,13 @@ class A2AIngressIdentity:
     target_a2a_agent_id: str
     authn_mode: str
     caller_runtime_id: str | None = None
+    task_binding: A2AIngressTaskBinding | None = None
+    verified_request_body: bytes | None = field(default=None, repr=False)
+    sub_account_id: str | None = None
 
     def validate(self) -> None:
+        if self.task_binding is not None:
+            self.task_binding.validate()
         values = {
             "account_id": self.account_id,
             "caller_principal_type": self.caller_principal_type,
@@ -58,21 +147,21 @@ class A2AIngressIdentity:
         }
         missing = [name for name, value in values.items() if not str(value).strip()]
         if missing:
-            raise PermissionError(
-                "verified Gateway identity is missing " + ", ".join(missing)
-            )
+            raise PermissionError("verified Gateway identity is missing " + ", ".join(missing))
         if self.caller_principal_type not in _CALLER_PRINCIPAL_TYPES:
             raise PermissionError("verified Gateway identity has an unsupported caller type")
         if self.authn_mode != _AUTHN_MODE_BY_CALLER_TYPE[self.caller_principal_type]:
             raise PermissionError("verified Gateway identity has an invalid authentication mode")
-        if self.caller_principal_type == "runtime" and not str(
-            self.caller_runtime_id or ""
-        ).strip():
+        if (
+            self.caller_principal_type == "runtime"
+            and not str(self.caller_runtime_id or "").strip()
+        ):
             raise PermissionError("verified runtime caller identity is missing caller runtime")
         if self.caller_principal_type != "runtime" and self.caller_runtime_id is not None:
             raise PermissionError("verified non-runtime caller identity includes a caller runtime")
         for field_name, limit in (
             ("account_id", 64),
+            ("sub_account_id", 64),
             ("tenant_id", 64),
             ("caller_principal_type", 16),
             ("caller_principal_id", 128),
@@ -106,9 +195,13 @@ class A2AIngressIdentity:
             tenant_id=self.tenant_id,
             caller_principal_type=self.caller_principal_type,
             caller_principal_id=self.caller_principal_id,
+            sub_account_id=self.sub_account_id,
         )
 
     def owner_key(self) -> str:
+        if self.caller_principal_type == "user":
+            canonical = self.context_identity().canonical_owner().encode("utf-8")
+            return "a2a-user-v1:" + hashlib.sha256(canonical).hexdigest()
         return "/".join(
             (
                 self.account_id.strip(),
@@ -215,10 +308,7 @@ class A2ATrustedIdentityResolver:
             and identity.account_id != self._expected_account_id
         ):
             raise PermissionError("verified Gateway identity targets a different account")
-        if (
-            self._expected_tenant_id is not None
-            and identity.tenant_id != self._expected_tenant_id
-        ):
+        if self._expected_tenant_id is not None and identity.tenant_id != self._expected_tenant_id:
             raise PermissionError("verified Gateway identity targets a different tenant")
         if (
             self._expected_target_agent_id is not None
@@ -293,6 +383,9 @@ class A2AGatewayIdentityMiddleware(BaseHTTPMiddleware):
 
 
 __all__ = [
+    "A2AApiKeyPrincipal",
+    "A2AAuthnMode",
+    "A2A_AUTHN_MODES",
     "A2AGatewayIdentityMiddleware",
     "A2AIngressTargetBinding",
     "A2AIngressIdentity",
@@ -301,4 +394,5 @@ __all__ = [
     "CallableGatewayProbeVerifier",
     "GatewayIdentityVerifier",
     "GatewayProbeVerifier",
+    "canonical_a2a_authn_mode",
 ]

ksadk/a2a/ids.py

@@ -8,14 +8,25 @@ _UUID4_HEX = re.compile(r"^[0-9a-f]{12}4[0-9a-f]{3}[89ab][0-9a-f]{15}$")
 
 
 def is_a2a_resource_id(value: str, prefix: str) -> bool:
-    """Return whether value is `<prefix><uuid4_hex>` with a lowercase compact UUID."""
-    return value.startswith(prefix) and bool(_UUID4_HEX.fullmatch(value.removeprefix(prefix)))
+    """Accept persisted Server IDs and the original prefixed SDK declarations.
+
+    Preserve the exact ID: adding/removing prefixes changes registry lookup,
+    permit claims and target binding. Server spaces use as-<12 hex>, registered
+    agents and versions use compact UUID4, while tasks retain a2a-task-.
+    """
+    if value.startswith(prefix) and _UUID4_HEX.fullmatch(value.removeprefix(prefix)):
+        return True
+    if prefix in {"a2a-agent-", "a2a-version-"}:
+        return bool(_UUID4_HEX.fullmatch(value))
+    if prefix == "a2a-space-":
+        return bool(re.fullmatch(r"as-[0-9a-f]{12}", value))
+    return False
 
 
 def require_a2a_resource_id(value: str, prefix: str, *, field_name: str) -> str:
     """Validate an AgentEngine A2A resource ID and return it unchanged."""
     if not is_a2a_resource_id(value, prefix):
-        raise ValueError(f"{field_name} must use the {prefix}<uuid4_hex> format")
+        raise ValueError(f"{field_name} must use a Server resource ID or {prefix}<uuid4_hex>")
     return value
 
 

ksadk/a2a/inbound_kernel.py

@@ -0,0 +1,133 @@
+"""Managed A2A input admitted by Server, never by a local self-signed permit."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from collections.abc import AsyncIterator
+from typing import Any
+from uuid import UUID
+
+from ksadk.a2a.identity import A2AIngressIdentity
+from ksadk.kernel.contracts import AgentControlReceipt, SessionEventEnvelope
+
+
+class ManagedKernelRequestError(RuntimeError):
+    """Admission failed or its outcome is unknown; preserve the durable Task."""
+
+
+@dataclass(frozen=True)
+class InboundKernelSubmission:
+    session_id: str
+    agent_id: str
+    receipt: AgentControlReceipt
+
+    @classmethod
+    def from_wire(cls, data: dict[str, Any]) -> InboundKernelSubmission:
+        session_id = data.get("SessionId")
+        agent_id = data.get("AgentId")
+        if not isinstance(session_id, str) or not session_id.startswith("a2a-kernel-") or len(session_id) > 128:
+            raise ValueError("invalid Server-derived A2A session")
+        if not isinstance(agent_id, str) or not agent_id.startswith("ar-") or len(agent_id) > 64:
+            raise ValueError("invalid Server A2A target")
+        receipt = AgentControlReceipt.model_validate(data.get("Receipt"))
+        if receipt.command_id != UUID(data.get("CommandId", "")):
+            raise ValueError("Server receipt command identity mismatch")
+        if receipt.status in {"accepted", "duplicate"} and (
+            receipt.accepted_seq is None or receipt.accepted_seq < 1
+        ):
+            raise ValueError("accepted A2A submission has no durable command sequence")
+        return cls(session_id=session_id, agent_id=agent_id, receipt=receipt)
+
+
+def verified_inbound_message(identity: A2AIngressIdentity) -> dict[str, Any]:
+    """Extract the original Message without protobuf alias/default rewriting."""
+    identity.validate()
+    binding = identity.task_binding
+    if binding is None or binding.operation != "send_message" or identity.verified_request_body is None:
+        raise PermissionError("managed Kernel send requires verified Gateway message provenance")
+    try:
+        body = json.loads(identity.verified_request_body)
+        if not isinstance(body, dict):
+            raise ValueError("request must be an object")
+        if "jsonrpc" in body:
+            if body.get("jsonrpc") != "2.0" or body.get("method") not in {
+                "message/send", "message/stream", "SendMessage", "SendStreamingMessage"
+            }:
+                raise ValueError("request is not a send")
+            body = body.get("params")
+        message = body.get("message") if isinstance(body, dict) else None
+        if not isinstance(message, dict):
+            raise ValueError("request has no Message")
+        return message
+    except (ValueError, UnicodeError, RecursionError) as exc:
+        raise PermissionError("verified Gateway message cannot be decoded") from exc
+
+
+async def submit_verified_inbound(
+    client: Any, identity: A2AIngressIdentity, *, remote_task_id: str, remote_context_id: str,
+    continuation: dict[str, Any] | None = None,
+) -> InboundKernelSubmission:
+    message = verified_inbound_message(identity)
+    result = await client.submit_inbound_message(
+        platform_task_id=identity.task_binding.platform_task_id,
+        target_version_id=identity.task_binding.target_version_id,
+        remote_task_id=remote_task_id, remote_context_id=remote_context_id,
+        message=message,
+        **({"continuation": continuation} if continuation is not None else {}),
+    )
+    if result.agent_id != identity.target_agent_id:
+        raise PermissionError("Server admission target differs from verified Gateway target")
+    return result
+
+
+async def stream_inbound_kernel_facts(
+    submission: InboundKernelSubmission, events: Any, *, expected_run_id: str | None = None,
+    after_seq: int = 0,
+    stop_at_waiting: bool = True,
+) -> AsyncIterator[SessionEventEnvelope]:
+    """Read only this admitted command's run from the local durable event log.
+
+    This is an internal projection after Server authorization, not a public
+    subscription endpoint. Never infer completion from EOF or another run.
+    """
+    receipt = submission.receipt
+    if receipt.status not in {"accepted", "duplicate"}:
+        raise RuntimeError("Server did not accept the A2A Kernel submission")
+    if receipt.accepted_seq is None or receipt.accepted_seq < 1:
+        raise RuntimeError("Server admission has no durable command sequence")
+    if expected_run_id and receipt.run_id and expected_run_id != receipt.run_id:
+        raise RuntimeError("Server receipt changed the resumed run")
+    run_id = receipt.run_id or expected_run_id
+    # accepted_seq is the inbox order, not a SessionEvent cursor. Only a
+    # previously observed durable event seq may advance this subscription.
+    if type(after_seq) is not int or after_seq < 0:
+        raise ValueError("invalid persisted Kernel event cursor")
+    cursor = after_seq
+    command_id = str(receipt.command_id)
+    async for fact in events.subscribe(submission.session_id, cursor):
+        if fact.session_id != submission.session_id:
+            raise PermissionError("Kernel event store returned another session")
+        if fact.seq <= cursor:
+            continue
+        cursor = fact.seq
+        if fact.event_type == "control.command_rejected" and fact.payload.get("command_id") == command_id:
+            raise RuntimeError("Kernel rejected the admitted A2A command")
+        if fact.family == "control" and fact.event_type == "control.run_transition" and fact.causation_id == command_id:
+            if not fact.run_id or fact.payload.get("run_id") != fact.run_id:
+                raise RuntimeError("Kernel command has an invalid run binding")
+            if run_id is not None and run_id != fact.run_id:
+                raise RuntimeError("Kernel command maps to conflicting runs")
+            run_id = fact.run_id
+        if not run_id or fact.run_id != run_id:
+            continue
+        yield fact
+        # The worker persists interaction.requested before WAITING. Return all
+        # facts through the state transition so the caller can persist both the
+        # pending interaction and its exact replay cursor before replying.
+        boundaries = {"completed", "failed", "cancelled", "interrupted"}
+        if stop_at_waiting:
+            boundaries.add("waiting")
+        if fact.family == "control" and fact.event_type == "control.run_transition" and fact.payload.get("state") in boundaries:
+            return
+    raise ManagedKernelRequestError("Kernel event stream ended without a durable run boundary")

ksadk/a2a/interaction_wire.py

@@ -0,0 +1,76 @@
+"""Public A2A interaction hints, never permits or native resume references."""
+
+import json
+
+from ksadk.events.canonical import ApprovalRequest
+from ksadk.kernel.approval_presentation import approval_presentation
+
+
+def approval_from_presentation(*, call_id: str, presentation: dict) -> ApprovalRequest:
+    """Project the Kernel's public preview, without copying its private record."""
+    title = presentation.get("title") or "Remote approval"
+    description = presentation.get("description") or "Approval required"
+    try:
+        payload = json.loads(description)
+    except (ValueError, TypeError):
+        payload = None
+    arguments = payload.get("arguments") if isinstance(payload, dict) else None
+    detail = {
+        "name": title,
+        "args": arguments if isinstance(arguments, dict) else {"description": description},
+        "prompt": description,
+    }
+    risk = payload.get("risk") if isinstance(payload, dict) else None
+    if isinstance(risk, str) and risk in {"low", "medium", "high", "critical"}:
+        detail["risk"] = risk
+    return ApprovalRequest(call_id=call_id, kind="tool", detail=detail)
+
+
+def approval_metadata(request: ApprovalRequest) -> dict:
+    """Preserve review semantics while keeping continuation authority private.
+
+    Legacy consumers can render the enum as structured input. New consumers
+    must still commit the user's decision through their own interaction ledger;
+    this remote declaration cannot authorize a call or select a provider.
+    """
+    presentation = approval_presentation(request)
+    return {
+        "input_schema": {"type": "string", "enum": ["approve", "reject"]},
+        "ksadk_interaction": {
+            "version": 1,
+            "kind": "approval",
+            "allowed_decisions": ["approve", "reject"],
+            "presentation": {
+                "title": presentation.title,
+                "description": presentation.description,
+            },
+        },
+    }
+
+
+def parse_approval_metadata(metadata: dict, *, call_id: str) -> ApprovalRequest | None:
+    """Reject malformed typed hints; never read provider or resume data from wire."""
+    value = metadata.get("ksadk_interaction")
+    if value is None:
+        return None
+    if (not isinstance(value, dict)
+            or set(value) != {"version", "kind", "allowed_decisions", "presentation"}
+            or isinstance(value.get("version"), bool) or value.get("version") != 1
+            or value.get("kind") != "approval"
+            or value.get("allowed_decisions") != ["approve", "reject"]):
+        raise ValueError("A2A_INTERACTION_DECLARATION_INVALID")
+    presentation = value["presentation"]
+    if (not isinstance(presentation, dict)
+            or set(presentation) != {"title", "description"}
+            or not isinstance(presentation["title"], str)
+            or len(presentation["title"]) > 128
+            or not isinstance(presentation["description"], str)
+            or len(presentation["description"]) > 96000
+            or metadata.get("input_schema") != {"type": "string", "enum": ["approve", "reject"]}):
+        raise ValueError("A2A_INTERACTION_DECLARATION_INVALID")
+    projected = approval_from_presentation(call_id=call_id, presentation=presentation)
+    # Reapply redaction to untrusted remote preview fields.
+    safe = approval_presentation(projected)
+    return approval_from_presentation(
+        call_id=call_id, presentation={"title": safe.title, "description": safe.description},
+    )