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

ksadk/conversations/tool_receipt_resume.py

@@ -0,0 +1,387 @@
+"""Durable receipt helpers used by approval resume orchestration."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import uuid
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import replace
+from typing import Any
+
+from ksadk.conversations.runtime_persistence import append_conversation_event
+from ksadk.sessions import SessionEvent, ToolReceiptClaim
+
+
+class ToolReceiptUncertainError(ValueError):
+    """A durable receipt exists without a safely replayable terminal result."""
+
+    def __init__(self, idempotency_key: str | None = None) -> None:
+        self.idempotency_key = str(idempotency_key or "")
+        detail = "tool receipt execution is uncertain; reconciliation required"
+        if self.idempotency_key:
+            detail += f"; idempotency_key={self.idempotency_key}"
+        super().__init__(detail)
+
+
+async def claim_receipt_for_execution(
+    *,
+    service: Any,
+    session_id: str,
+    receipt: Mapping[str, Any],
+    tool_name: str,
+    call_args: Mapping[str, Any],
+    invocation_id: str,
+    preclaimed_receipt: tuple[dict[str, Any], ToolReceiptClaim] | None,
+) -> ToolReceiptClaim:
+    claim = (
+        preclaimed_receipt[1]
+        if preclaimed_receipt is not None
+        else await service.claim_tool_receipt(
+            session_id,
+            idempotency_key=str(receipt["idempotency_key"]),
+            tool_name=tool_name,
+            arguments_digest=_tool_receipt_arguments_digest(call_args),
+            claim_id=f"{invocation_id}:{uuid.uuid4().hex}",
+        )
+    )
+    return _validate_tool_receipt_claim(claim)
+
+
+async def replay_existing_tool_receipt_event(
+    *,
+    existing_event: SessionEvent,
+    receipt: Mapping[str, Any],
+    session_id: str,
+    invocation_id: str,
+    run_id: str,
+    tool_name: str,
+    call_args: Mapping[str, Any],
+    resume_input: Mapping[str, Any],
+    session_service_provider: Callable[[], Any],
+) -> dict[str, Any]:
+    from ksadk.conversations.runtime_resume import _validate_tool_receipt_event
+
+    existing_metadata = existing_event.metadata or {}
+    _validate_tool_receipt_event(existing_event)
+    output = existing_metadata["tool_output"]
+    if isinstance(output, Mapping):
+        output = {**dict(output), "replayed": True}
+    replayed_receipt = {
+        **dict((existing_metadata.get("tool_receipt") or receipt)),
+        "replayed": True,
+        "replayed_from_event_id": existing_event.id,
+    }
+    await append_conversation_event(
+        session_id=session_id,
+        author="tool",
+        role="user",
+        text=str(output),
+        invocation_id=invocation_id,
+        event_type="tool_result",
+        session_service_provider=session_service_provider,
+        metadata={
+            "tool_name": tool_name,
+            "tool_args": dict(call_args),
+            "tool_output": output,
+            "run_id": run_id,
+            "approval_request_id": resume_input.get("approval_request_id")
+            or resume_input.get("interrupt_id"),
+            "tool_receipt": replayed_receipt,
+            "replayed": True,
+        },
+    )
+    return {"type": "function_call_output", "call_id": run_id, "output": output}
+
+
+def _validate_tool_receipt_claim_state(state: str, idempotency_key: str = "") -> str:
+    normalized = str(state or "").strip().lower()
+    if normalized not in {"unknown", "completed", "failed"}:
+        raise ToolReceiptUncertainError(idempotency_key)
+    return normalized
+
+
+def _validate_tool_receipt_claim(claim: ToolReceiptClaim) -> ToolReceiptClaim:
+    state = _validate_tool_receipt_claim_state(claim.state, claim.idempotency_key)
+    if isinstance(claim.output, Mapping) and state in {"completed", "failed"}:
+        expected = (
+            "completed"
+            if claim.output.get("status") == "accepted_not_extracted"
+            else ("failed" if claim.output.get("ok") is False else "completed")
+        )
+        if state != expected:
+            raise ToolReceiptUncertainError(claim.idempotency_key)
+    return claim
+
+
+def _tool_receipt_arguments_digest(tool_args: Mapping[str, Any]) -> str:
+    try:
+        encoded = json.dumps(tool_args, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+    except TypeError:
+        encoded = json.dumps(str(tool_args), ensure_ascii=False, separators=(",", ":"))
+    return hashlib.sha256(encoded.encode("utf-8")).hexdigest()
+
+
+def _pending_approval_events(events: Sequence[SessionEvent]) -> list[SessionEvent]:
+    from ksadk.conversations.runtime_resume import (
+        _approval_lifecycle_event_type,
+        _approval_request_id_from_event,
+    )
+
+    pending: list[SessionEvent] = []
+    for event in events:
+        event_type = _approval_lifecycle_event_type(event)
+        if event_type == "approval_request":
+            pending.append(event)
+            continue
+        if event_type != "approval_response" or not pending:
+            continue
+        resume_input = (event.metadata or {}).get("resume_input")
+        response_id = ""
+        if isinstance(resume_input, Mapping):
+            response_id = str(
+                resume_input.get("approval_request_id")
+                or resume_input.get("interrupt_id") or resume_input.get("id") or ""
+            )
+        content = event.content or {}
+        payload = content.get("runtime_event") or content.get("payload")
+        if not response_id and isinstance(payload, Mapping):
+            response_id = str(
+                payload.get("interaction_id") or payload.get("approval_id")
+                or payload.get("call_id") or ""
+            )
+        if response_id:
+            remaining = []
+            for item in pending:
+                request_ids = {_approval_request_id_from_event(item)}
+                request_payload = (item.content or {}).get("runtime_event")
+                if isinstance(request_payload, Mapping):
+                    request_ids.add(str(request_payload.get("interaction_id") or ""))
+                    request = request_payload.get("request")
+                    if isinstance(request, Mapping):
+                        request_ids.add(str(request.get("call_id") or ""))
+                if response_id not in request_ids:
+                    remaining.append(item)
+            pending = remaining
+        else:
+            pending.pop()
+    return pending
+
+
+def _has_pending_approval_for_resume(
+    events: Sequence[SessionEvent], resume_input: Mapping[str, Any]
+) -> bool:
+    from ksadk.conversations.runtime_resume import (
+        _approval_request_id_from_event,
+    )
+
+    decision = resume_input.get("approval")
+    decision = decision if isinstance(decision, Mapping) else {}
+    request_id = str(
+        resume_input.get("approval_request_id") or resume_input.get("interrupt_id")
+        or decision.get("approval_request_id") or ""
+    )
+    pending = _pending_approval_events(events)
+    if not request_id:
+        return bool(pending)
+    return any(_approval_request_id_from_event(event) == request_id for event in pending)
+
+
+async def _claim_approved_builtin_tool_resume(
+    *,
+    session_id: str,
+    invocation_id: str,
+    resume_input: Mapping[str, Any],
+    session_service_provider: Callable[[], Any],
+    existing_events: Sequence[SessionEvent],
+    require_existing: bool = False,
+) -> tuple[dict[str, Any] | None, ToolReceiptClaim | None]:
+    """Reserve an approved builtin before consuming its approval response."""
+
+    from ksadk.conversations.runtime_resume import (
+        LegacyToolReceiptCheckpointAmbiguityError,
+        _builtin_tool_callable,
+        _find_legacy_tool_receipt_event_for_resume,
+        _find_tool_receipt_event_by_key,
+        _latest_checkpoint_metadata_for_run,
+        _tool_receipt_metadata,
+        _tool_resume_run_id,
+        _validate_tool_receipt_event,
+    )
+
+    approval = resume_input.get("approval")
+    if not isinstance(approval, Mapping) or not bool(approval.get("approved")):
+        return None, None
+    tool_name = str(resume_input.get("tool_name") or "").strip()
+    tool_args = resume_input.get("tool_args")
+    if not tool_name or not isinstance(tool_args, Mapping):
+        return None, None
+    call_args = dict(tool_args)
+    run_id = _tool_resume_run_id(resume_input)
+    if not run_id:
+        return None, None
+    checkpoint_metadata = _latest_checkpoint_metadata_for_run(existing_events, run_id)
+    requested_checkpoint_id = str(resume_input.get("checkpoint_id") or "").strip()
+    if requested_checkpoint_id:
+        checkpoint_metadata = {**checkpoint_metadata, "checkpoint_id": requested_checkpoint_id}
+    receipt = _tool_receipt_metadata(
+        session_id=session_id,
+        run_id=run_id,
+        tool_call_id=run_id,
+        tool_name=tool_name,
+        tool_args=call_args,
+        checkpoint_id=checkpoint_metadata.get("checkpoint_id"),
+        framework=checkpoint_metadata.get("framework"),
+        framework_ref=checkpoint_metadata.get("framework_ref"),
+    )
+    existing_event = _find_tool_receipt_event_by_key(
+        existing_events,
+        receipt["idempotency_key"],
+        expected_receipt=receipt,
+        expected_tool_args=call_args,
+    )
+    if existing_event is not None:
+        _validate_tool_receipt_event(existing_event)
+        return receipt, None
+    if requested_checkpoint_id:
+        legacy_event = _find_legacy_tool_receipt_event_for_resume(
+            session_id=session_id,
+            resume_input=resume_input,
+            events=existing_events,
+        )
+        if legacy_event is not None:
+            raise LegacyToolReceiptCheckpointAmbiguityError()
+    if _builtin_tool_callable(tool_name) is None:
+        return None, None
+    if require_existing:
+        # No approval is pending. A crash retry may only inspect/replay the
+        # previous claim; it must not acquire a new right to perform effects.
+        claim = await session_service_provider().get_tool_receipt_claim(
+            session_id, idempotency_key=str(receipt["idempotency_key"])
+        )
+        if claim is None:
+            raise ValueError("Responses resume input requires a pending approval_request")
+        if (claim.tool_name != tool_name
+                or claim.arguments_digest != _tool_receipt_arguments_digest(call_args)):
+            raise ValueError("tool receipt idempotency key conflict")
+        return receipt, _validate_tool_receipt_claim(replace(claim, acquired=False))
+    claim = await session_service_provider().claim_tool_receipt(
+        session_id,
+        idempotency_key=str(receipt["idempotency_key"]),
+        tool_name=tool_name,
+        arguments_digest=_tool_receipt_arguments_digest(call_args),
+        claim_id=f"{invocation_id}:{uuid.uuid4().hex}",
+    )
+    _validate_tool_receipt_claim(claim)
+    return receipt, claim
+
+
+
+async def replay_claimed_tool_receipt(
+    *,
+    claim: ToolReceiptClaim,
+    receipt: Mapping[str, Any],
+    session_id: str,
+    invocation_id: str,
+    run_id: str,
+    tool_name: str,
+    call_args: Mapping[str, Any],
+    resume_input: Mapping[str, Any],
+    session_service_provider: Callable[[], Any],
+) -> dict[str, Any]:
+    _validate_tool_receipt_claim(claim)
+    if claim.state == "unknown":
+        raise ToolReceiptUncertainError(claim.idempotency_key)
+    output = claim.output
+    if isinstance(output, Mapping):
+        output = {**dict(output), "replayed": True}
+    replayed_receipt = {
+        **dict(receipt),
+        "status": claim.state,
+        "replayed": True,
+        "replayed_from_claim": True,
+    }
+    await append_conversation_event(
+        session_id=session_id,
+        author="tool",
+        role="user",
+        text=str(output),
+        invocation_id=invocation_id,
+        event_type="tool_result",
+        session_service_provider=session_service_provider,
+        metadata={
+            "tool_name": tool_name,
+            "tool_args": dict(call_args),
+            "tool_output": output,
+            "run_id": run_id,
+            "approval_request_id": resume_input.get("approval_request_id")
+            or resume_input.get("interrupt_id"),
+            "tool_receipt": replayed_receipt,
+            "replayed": True,
+        },
+    )
+    return {"type": "function_call_output", "call_id": run_id, "output": output}
+
+
+async def claim_or_replay_tool_receipt(
+    *,
+    service: Any,
+    session_id: str,
+    receipt: dict[str, Any],
+    tool_name: str,
+    call_args: Mapping[str, Any],
+    invocation_id: str,
+    run_id: str,
+    resume_input: Mapping[str, Any],
+    session_service_provider: Callable[[], Any],
+    preclaimed_receipt: tuple[dict[str, Any], ToolReceiptClaim] | None,
+) -> tuple[ToolReceiptClaim, dict[str, Any] | None]:
+    claim = await claim_receipt_for_execution(
+        service=service,
+        session_id=session_id,
+        receipt=receipt,
+        tool_name=tool_name,
+        call_args=call_args,
+        invocation_id=invocation_id,
+        preclaimed_receipt=preclaimed_receipt,
+    )
+    if claim.acquired:
+        return claim, None
+    return claim, await replay_claimed_tool_receipt(
+        claim=claim,
+        receipt=receipt,
+        session_id=session_id,
+        invocation_id=invocation_id,
+        run_id=run_id,
+        tool_name=tool_name,
+        call_args=call_args,
+        resume_input=resume_input,
+        session_service_provider=session_service_provider,
+    )
+
+
+async def settle_claimed_tool_receipt(
+    *,
+    service: Any,
+    claim: ToolReceiptClaim,
+    receipt: dict[str, Any],
+    session_id: str,
+    tool_name: str,
+    call_args: Mapping[str, Any],
+    output: Any,
+) -> None:
+    from ksadk.conversations.runtime_resume import _tool_receipt_status_from_output
+
+    status = _tool_receipt_status_from_output(output)
+    settled = await service.settle_tool_receipt(
+        session_id,
+        idempotency_key=str(receipt["idempotency_key"]),
+        tool_name=tool_name,
+        arguments_digest=_tool_receipt_arguments_digest(call_args),
+        claim_id=claim.claim_id,
+        state="failed" if status == "failed" else "completed",
+        output=output,
+    )
+    if settled.claim_id != claim.claim_id or settled.state == "unknown":
+        raise ToolReceiptUncertainError(claim.idempotency_key)
+    receipt["status"] = status

ksadk/conversations/tool_receipts.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from typing import Mapping
+
+from ksadk.sessions import SessionEvent
+
+_KNOWN_TOOL_RECEIPT_STATUSES = frozenset({"completed", "failed", "succeeded"})
+
+
+def _validate_tool_receipt_event(event: SessionEvent) -> str:
+    """Reject malformed persisted output/status pairs before replay."""
+
+    metadata = event.metadata or {}
+    if "tool_output" not in metadata:
+        raise ValueError("tool receipt is missing tool_output")
+    receipt = metadata.get("tool_receipt")
+    if not isinstance(receipt, Mapping):
+        raise ValueError("tool receipt is missing receipt metadata")
+    status = str(receipt.get("status") or "").strip().lower()
+    if status not in _KNOWN_TOOL_RECEIPT_STATUSES:
+        raise ValueError(f"tool receipt has unknown status {status!r}")
+    output = metadata["tool_output"]
+    if isinstance(output, Mapping):
+        expected = (
+            "completed"
+            if output.get("status") == "accepted_not_extracted"
+            else ("failed" if output.get("ok") is False else "completed")
+        )
+        normalized_status = "completed" if status == "succeeded" else status
+        if normalized_status != expected:
+            raise ValueError("tool receipt status does not match mapping tool_output ok value")
+    return status

ksadk/deployment/env_forward.py

@@ -45,6 +45,11 @@ DEPLOY_PROCESS_ENV_DENYLIST = frozenset(
         "KSADK_GLOBAL_CONFIG_ENV_KEYS",
         "KSADK_UPDATED_AT",
         "KSADK_VERSION",
+        # Local Studio host selection must not change a hosted Runtime policy.
+        "KSADK_STUDIO_NATIVE_DEFAULT",
+        "KSADK_STUDIO_NATIVE_AGENT_IDS",
+        "KSADK_STUDIO_NATIVE_DURABLE",
+        "KSADK_STUDIO_AGENT_ID",
     }
 )
 

ksadk/deployment/manager.py

@@ -244,19 +244,28 @@ runtime_context = RuntimeLaunchContext(
     detection=detection_result,
     config=dict(getattr(detection_result, "raw_config", None) or {{}}),
 )
-# managed A2A discovery-only card:KSADK_A2A_RUNTIME_ID 非空时挂
-# /.well-known/agent-card.json;注册前即可被 server 探测(a2a-runtime-inbound-wiring)。
-_managed_a2a_card = None
+# Runtime identity is available before registration for discovery.  Operator
+# enables the complete composition only after every Secret projection exists.
+_managed_a2a_bootstrap = None
+_a2a_adapter = None
 if os.environ.get("KSADK_A2A_RUNTIME_ID", "").strip():
-    from ksadk.managed_a2a_card import build_managed_a2a_card_if_configured
+    if os.environ.get("KSADK_A2A_MANAGED_BOOTSTRAP_ENABLED", "").strip().lower() == "true":
+        from ksadk.a2a.platform import build_managed_a2a_bootstrap_from_env
+        from ksadk.runtime.factory import create_runtime_adapter
 
-    _managed_a2a_card = build_managed_a2a_card_if_configured()
+        _managed_a2a_bootstrap = build_managed_a2a_bootstrap_from_env()
+        _a2a_adapter = create_runtime_adapter(runtime_context)
+    else:
+        from ksadk.managed_a2a_card import build_managed_a2a_card_if_configured
+
+        _managed_a2a_bootstrap = build_managed_a2a_card_if_configured()
 app = create_runtime_app(
     RuntimeAppConfig(
         runtime_type=detection_result.type.value,
         runtime_executor=RuntimeExecutor(build_default_runtime_registry()),
         launch_context=runtime_context,
-        a2a=_managed_a2a_card,
+        a2a=_managed_a2a_bootstrap,
+        a2a_runtime_adapter=_a2a_adapter,
     ),
     configure_runtime_app,
 )