agentcore-cli 0.31.1__py3-none-any.whl

agentcore/aws/agentcore_payments.py

@@ -0,0 +1,430 @@
+"""Payment control/data-plane operations (port of ``agentcore-payments.ts``).
+
+Upstream calls these with SigV4-signed ``fetch`` requests (8s timeout); the raw requests are kept
+so paths, payloads, error redaction and the passthrough of the service JSON are unchanged.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from typing import Any, Literal, NotRequired, TypedDict
+
+import urllib3
+
+from agentcore.aws._http import HttpResponse, encode_uri_component, signed_request
+from agentcore.aws.stage_endpoint import control_plane_endpoint, data_plane_endpoint
+from agentcore.lib.utils.json_format import to_json_string
+
+_REQUEST_TIMEOUT_S = 8.0
+
+
+class PaymentApiError(RuntimeError):
+    """Payment API failure; ``code`` carries the service's ``code``/``__type`` when present."""
+
+    def __init__(self, message: str, code: str | None = None):
+        super().__init__(message)
+        self.code = code
+
+    @property
+    def message(self) -> str:
+        return str(self)
+
+
+# --- Credential provider options ---
+
+
+@dataclass(slots=True)
+class CoinbaseCdpCredentialProviderOptions:
+    region: str
+    name: str
+    api_key_id: str
+    api_key_secret: str
+    wallet_secret: str
+    vendor: Literal["CoinbaseCDP"] = "CoinbaseCDP"
+
+
+@dataclass(slots=True)
+class StripePrivyCredentialProviderOptions:
+    region: str
+    name: str
+    app_id: str
+    app_secret: str
+    authorization_private_key: str
+    authorization_id: str
+    vendor: Literal["StripePrivy"] = "StripePrivy"
+
+
+CreatePaymentCredentialProviderOptions = CoinbaseCdpCredentialProviderOptions | StripePrivyCredentialProviderOptions
+UpdatePaymentCredentialProviderOptions = CreatePaymentCredentialProviderOptions
+
+
+class PaymentCredentialProviderApiResult(TypedDict):
+    credentialProviderArn: str
+    status: str
+
+
+class PaymentCredentialProviderDetail(TypedDict):
+    credentialProviderArn: str
+    name: str
+    status: str
+
+
+class PaymentManagerDetail(TypedDict):
+    paymentManagerId: str
+    paymentManagerArn: str
+    name: str
+    status: str
+    description: NotRequired[str]
+    roleArn: NotRequired[str]
+
+
+PaymentConnectorStatus = Literal[
+    "CREATING",
+    "UPDATING",
+    "DELETING",
+    "READY",
+    "CREATE_FAILED",
+    "UPDATE_FAILED",
+    "DELETE_FAILED",
+    "AWS_MARKETPLACE_SUBSCRIPTION_REQUIRED",
+    "PENDING_AUTHENTICATION",
+    "PROVISIONING",
+    "AUTHENTICATION_EXPIRED",
+    "AUTHENTICATION_FAILED",
+]
+
+
+class PaymentCredentialProviderConfiguration(TypedDict, total=False):
+    coinbaseCDP: dict[str, str]
+    stripePrivy: dict[str, str]
+
+
+class PaymentConnectorDetail(TypedDict):
+    paymentConnectorId: str
+    name: str
+    description: NotRequired[str]
+    type: Literal["CoinbaseCDP", "StripePrivy"]
+    credentialProviderConfigurations: list[PaymentCredentialProviderConfiguration]
+    createdAt: float | str
+    lastUpdatedAt: float | str
+    status: PaymentConnectorStatus
+    authorizationUrl: NotRequired[str]
+
+
+# ============================================================================
+# Error helpers
+# ============================================================================
+
+
+def rethrow_with_context(prefix: str, err: object) -> PaymentApiError:
+    """Wrap ``err`` with a contextual prefix, preserving its structured ``code``."""
+    code = getattr(err, "code", None)
+    wrapped = PaymentApiError(f"{prefix}: {err}", code if isinstance(code, str) else None)
+    if isinstance(err, BaseException):
+        wrapped.__cause__ = err
+    return wrapped
+
+
+def redact_secrets(text: str, secrets: Iterable[str] | None) -> str:
+    """Replace every literal occurrence of each secret with ``[REDACTED]``."""
+    out = text
+    for secret in secrets or []:
+        if isinstance(secret, str) and secret:
+            out = out.replace(secret, "[REDACTED]")
+    return out
+
+
+def sanitize_error_body(body: str, secrets: Iterable[str] | None) -> str:
+    """Error excerpt: parsed ``code``/``__type`` and redacted ``message``; plus the redacted body under ``DEBUG``."""
+    if not body:
+        return ""
+    secret_list = list(secrets or [])
+    parts: list[str] = []
+    try:
+        parsed = json.loads(body)
+        if isinstance(parsed, dict):
+            code = parsed.get("code") if parsed.get("code") is not None else parsed.get("__type")
+            if isinstance(code, str):
+                parts.append(code)
+            message = next(
+                (parsed[k] for k in ("message", "Message", "errorMessage") if parsed.get(k) is not None), None
+            )
+            if isinstance(message, str):
+                parts.append(redact_secrets(message, secret_list))
+    except ValueError:
+        pass  # body is not JSON
+    if os.environ.get("DEBUG"):
+        parts.append(redact_secrets(body, secret_list)[:500])
+    return " — ".join(parts)
+
+
+def _error_code(body: str) -> str | None:
+    try:
+        parsed = json.loads(body)
+    except ValueError:
+        return None
+    if not isinstance(parsed, dict):
+        return None
+    code = parsed.get("code") if parsed.get("code") is not None else parsed.get("__type")
+    return code if isinstance(code, str) else None
+
+
+def _send(
+    *,
+    endpoint: str,
+    label: str,
+    region: str,
+    method: str,
+    path: str,
+    body: str | None,
+    extra_headers: Mapping[str, str] | None,
+    secrets_to_redact: Iterable[str] | None,
+) -> Any:
+    try:
+        response: HttpResponse = signed_request(
+            method, f"{endpoint}{path}", region=region, body=body, headers=extra_headers, timeout=_REQUEST_TIMEOUT_S
+        )
+    except (urllib3.exceptions.TimeoutError, TimeoutError) as exc:
+        raise PaymentApiError(
+            f"{label} request timed out (>8s) for {method} {path}. Check network connectivity and region."
+        ) from exc
+
+    if not response.ok:
+        try:
+            error_body = response.text()
+        except Exception:  # noqa: BLE001
+            error_body = ""
+        base = f"{label} error ({response.status})"
+        excerpt = sanitize_error_body(error_body, secrets_to_redact)
+        raise PaymentApiError(f"{base}: {excerpt}" if excerpt else base, _error_code(error_body))
+
+    if response.status == 204:
+        return {}
+    return response.json()
+
+
+def _signed_request(
+    *, region: str, method: str, path: str, body: str | None = None, secrets_to_redact: Iterable[str] | None = None
+) -> Any:
+    return _send(
+        endpoint=control_plane_endpoint(region),
+        label="Payment API",
+        region=region,
+        method=method,
+        path=path,
+        body=body,
+        extra_headers=None,
+        secrets_to_redact=secrets_to_redact,
+    )
+
+
+def _signed_data_plane_request(
+    *,
+    region: str,
+    method: str,
+    path: str,
+    body: str | None = None,
+    extra_headers: Mapping[str, str] | None = None,
+    secrets_to_redact: Iterable[str] | None = None,
+) -> Any:
+    return _send(
+        endpoint=data_plane_endpoint(region),
+        label="Payment data plane API",
+        region=region,
+        method=method,
+        path=path,
+        body=body,
+        extra_headers=extra_headers,
+        secrets_to_redact=secrets_to_redact,
+    )
+
+
+def _is_not_found(err: PaymentApiError) -> bool:
+    return err.code == "ResourceNotFoundException" or "(404)" in str(err)
+
+
+# ============================================================================
+# Payment credential providers
+# ============================================================================
+
+
+def _build_provider_config_payload(
+    options: CreatePaymentCredentialProviderOptions,
+) -> tuple[str, dict[str, Any], list[str]]:
+    """(vendor, providerConfigurationInput, literal secrets used only for redaction)."""
+    if isinstance(options, StripePrivyCredentialProviderOptions):
+        return (
+            "StripePrivy",
+            {
+                "stripePrivyConfiguration": {
+                    "appId": options.app_id,
+                    "appSecret": options.app_secret,
+                    "authorizationPrivateKey": options.authorization_private_key,
+                    "authorizationId": options.authorization_id,
+                }
+            },
+            [options.app_id, options.app_secret, options.authorization_private_key, options.authorization_id],
+        )
+    return (
+        "CoinbaseCDP",
+        {
+            "coinbaseCdpConfiguration": {
+                "apiKeyId": options.api_key_id,
+                "apiKeySecret": options.api_key_secret,
+                "walletSecret": options.wallet_secret,
+            }
+        },
+        [options.api_key_id, options.api_key_secret, options.wallet_secret],
+    )
+
+
+def _write_credential_provider(
+    options: CreatePaymentCredentialProviderOptions, operation: str, verb: str
+) -> PaymentCredentialProviderApiResult:
+    vendor, config_input, secrets = _build_provider_config_payload(options)
+    body = to_json_string(
+        {"name": options.name, "credentialProviderVendor": vendor, "providerConfigurationInput": config_input},
+        indent=None,
+    )
+    try:
+        data = _signed_request(
+            region=options.region,
+            method="POST",
+            path=f"/identities/{operation}",
+            body=body,
+            secrets_to_redact=secrets,
+        )
+    except Exception as exc:
+        raise rethrow_with_context(f'Failed to {verb} payment credential provider "{options.name}"', exc) from exc
+    return {"credentialProviderArn": data.get("credentialProviderArn"), "status": data.get("status")}
+
+
+def create_payment_credential_provider(
+    options: CreatePaymentCredentialProviderOptions,
+) -> PaymentCredentialProviderApiResult:
+    return _write_credential_provider(options, "CreatePaymentCredentialProvider", "create")
+
+
+def update_payment_credential_provider(
+    options: UpdatePaymentCredentialProviderOptions,
+) -> PaymentCredentialProviderApiResult:
+    return _write_credential_provider(options, "UpdatePaymentCredentialProvider", "update")
+
+
+def get_payment_credential_provider(*, region: str, name: str) -> PaymentCredentialProviderDetail | None:
+    """Provider details, or ``None`` if it does not exist."""
+    try:
+        return _signed_request(
+            region=region,
+            method="POST",
+            path="/identities/GetPaymentCredentialProvider",
+            body=to_json_string({"name": name}, indent=None),
+        )
+    except PaymentApiError as exc:
+        if _is_not_found(exc):
+            return None
+        raise rethrow_with_context(f'Failed to get payment credential provider "{name}"', exc) from exc
+    except Exception as exc:
+        raise rethrow_with_context(f'Failed to get payment credential provider "{name}"', exc) from exc
+
+
+def delete_payment_credential_provider(*, region: str, name: str) -> None:
+    try:
+        _signed_request(
+            region=region,
+            method="POST",
+            path="/identities/DeletePaymentCredentialProvider",
+            body=to_json_string({"name": name}, indent=None),
+        )
+    except Exception as exc:
+        raise rethrow_with_context(f'Failed to delete payment credential provider "{name}"', exc) from exc
+
+
+# ============================================================================
+# Payment managers / connectors
+# ============================================================================
+
+
+def _get_or_none(path: str, region: str, context: str) -> Any:
+    try:
+        return _signed_request(region=region, method="GET", path=path)
+    except PaymentApiError as exc:
+        if _is_not_found(exc):
+            return None
+        raise rethrow_with_context(context, exc) from exc
+    except Exception as exc:
+        raise rethrow_with_context(context, exc) from exc
+
+
+def get_payment_manager(*, region: str, payment_manager_id: str) -> PaymentManagerDetail | None:
+    return _get_or_none(
+        f"/payments/managers/{encode_uri_component(payment_manager_id)}",
+        region,
+        f'Failed to get payment manager "{payment_manager_id}"',
+    )
+
+
+def get_payment_connector(
+    *, region: str, payment_manager_id: str, payment_connector_id: str
+) -> PaymentConnectorDetail | None:
+    return _get_or_none(
+        f"/payments/managers/{encode_uri_component(payment_manager_id)}/connectors/"
+        + encode_uri_component(payment_connector_id),
+        region,
+        f'Failed to get payment connector "{payment_connector_id}"',
+    )
+
+
+# ============================================================================
+# Data plane: payment sessions
+# ============================================================================
+
+
+def get_or_create_payment_session(
+    *,
+    region: str,
+    manager_arn: str,
+    user_id: str,
+    default_spend_limit: str = "10.00",
+    default_expiry_minutes: int = 60,
+) -> str:
+    """Return an ACTIVE payment session for ``user_id``, creating one with the default budget if needed.
+
+    Uses the developer's credentials (ManagementRole).
+    """
+    user_id_header = {"X-Amzn-Bedrock-AgentCore-Payments-User-Id": user_id}
+
+    try:
+        listed = _signed_data_plane_request(
+            region=region,
+            method="POST",
+            path="/payments/listPaymentSessions",
+            body=to_json_string({"userId": user_id, "paymentManagerArn": manager_arn}, indent=None),
+            extra_headers=user_id_header,
+        )
+        active = [s for s in listed.get("paymentSessions") or [] if s.get("status") == "ACTIVE"]
+        if active:
+            return active[0]["paymentSessionId"]
+    except Exception:  # noqa: BLE001, S110 - fall through to create
+        pass
+
+    # CreatePaymentSession wraps the session in `paymentSession` (unlike the list response).
+    created = _signed_data_plane_request(
+        region=region,
+        method="POST",
+        path="/payments/createPaymentSession",
+        body=to_json_string(
+            {
+                "userId": user_id,
+                "paymentManagerArn": manager_arn,
+                "expiryTimeInMinutes": default_expiry_minutes,
+                "limits": {"maxSpendAmount": {"value": default_spend_limit, "currency": "USD"}},
+            },
+            indent=None,
+        ),
+        extra_headers=user_id_header,
+    )
+    return created["paymentSession"]["paymentSessionId"]

agentcore/aws/agentcore_recommendation.py

@@ -0,0 +1,140 @@
+"""Recommendation API operations (port of ``agentcore-recommendation.ts``).
+
+All Recommendation endpoints are on the data plane (as of upstream v0.31.1). Recommendations are
+one-shot and immutable: start, poll with get, stop via delete. Upstream calls these with
+SigV4-signed ``fetch`` requests; the raw requests are kept so payloads and the passthrough of the
+service JSON (e.g. ``statusReasons``, ``completedAt``) are unchanged.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, NotRequired, TypedDict
+
+from agentcore.aws._http import HttpResponse, query_string, signed_request
+from agentcore.aws._util import drop_none
+from agentcore.aws.stage_endpoint import data_plane_endpoint
+from agentcore.lib.errors.types import JobNotFoundError
+from agentcore.lib.utils.json_format import to_json_string
+
+RecommendationType = Literal["SYSTEM_PROMPT_RECOMMENDATION", "TOOL_DESCRIPTION_RECOMMENDATION"]
+
+# Input config: tagged union, populate only the member matching the type:
+#   {"systemPromptRecommendationConfig": {systemPrompt, agentTraces, evaluationConfig?}}
+#   {"toolDescriptionRecommendationConfig": {toolDescription, agentTraces}}
+RecommendationConfig = dict[str, Any]
+# Result: {"systemPromptRecommendationResult": {...}} or {"toolDescriptionRecommendationResult": {...}}
+RecommendationResult = dict[str, Any]
+
+
+class StartRecommendationResult(TypedDict):
+    recommendationId: str
+    recommendationArn: str
+    name: str
+    type: str
+    status: str
+    createdAt: NotRequired[str]
+    updatedAt: NotRequired[str]
+    requestId: NotRequired[str]
+
+
+class GetRecommendationResult(TypedDict):
+    recommendationId: str
+    recommendationArn: str
+    name: str
+    description: NotRequired[str]
+    type: str
+    recommendationConfig: NotRequired[RecommendationConfig]
+    status: str
+    statusReasons: NotRequired[list[str]]
+    createdAt: NotRequired[str]
+    updatedAt: NotRequired[str]
+    completedAt: NotRequired[str]
+    recommendationResult: NotRequired[RecommendationResult]
+    requestId: NotRequired[str]
+
+
+class RecommendationSummary(TypedDict):
+    recommendationId: str
+    recommendationArn: str
+    name: str
+    description: NotRequired[str]
+    type: str
+    status: str
+    createdAt: NotRequired[str]
+    updatedAt: NotRequired[str]
+
+
+class ListRecommendationsResult(TypedDict):
+    recommendationSummaries: list[RecommendationSummary]
+    nextToken: NotRequired[str]
+
+
+class DeleteRecommendationResult(TypedDict):
+    recommendationId: str
+    status: str
+
+
+def _signed_request(*, region: str, method: str, path: str, body: str | None = None) -> tuple[Any, str]:
+    endpoint = data_plane_endpoint(region)
+    response: HttpResponse = signed_request(method, f"{endpoint}{path}", region=region, body=body)
+    request_id = response.header("x-amzn-requestid") or "unknown"
+    if not response.ok:
+        message = f"Recommendation API error ({response.status}): {response.text()} [requestId: {request_id}]"
+        if response.status == 404:
+            raise JobNotFoundError(message, error_source="service")
+        raise RuntimeError(message)
+    if response.status == 204:
+        return {}, request_id
+    return response.json(), request_id
+
+
+def start_recommendation(
+    *,
+    region: str,
+    name: str,
+    type: RecommendationType,
+    recommendation_config: RecommendationConfig,
+    description: str | None = None,
+    kms_key_arn: str | None = None,
+    client_token: str | None = None,
+) -> StartRecommendationResult:
+    """Start a recommendation (202): PENDING -> IN_PROGRESS -> COMPLETED | FAILED."""
+    body: dict[str, Any] = {"name": name}
+    if description:
+        body["description"] = description
+    body["type"] = type
+    body["recommendationConfig"] = recommendation_config
+    if kms_key_arn:
+        body["kmsKeyArn"] = kms_key_arn
+    if client_token:
+        body["clientToken"] = client_token
+    data, request_id = _signed_request(
+        region=region, method="POST", path="/recommendations", body=to_json_string(body, indent=None)
+    )
+    if request_id:
+        data["requestId"] = request_id
+    return data
+
+
+def get_recommendation(*, region: str, recommendation_id: str) -> GetRecommendationResult:
+    """Recommendation status; ``recommendationResult`` is populated once COMPLETED."""
+    data, request_id = _signed_request(region=region, method="GET", path=f"/recommendations/{recommendation_id}")
+    if request_id:
+        data["requestId"] = request_id
+    return data
+
+
+def list_recommendations(
+    *, region: str, status: str | None = None, max_results: int | None = None, next_token: str | None = None
+) -> ListRecommendationsResult:
+    query = query_string({"status": status, "maxResults": max_results, "nextToken": next_token})
+    data, _ = _signed_request(region=region, method="GET", path=f"/recommendations{query}")
+    return drop_none(  # type: ignore[return-value]
+        {"recommendationSummaries": data.get("recommendationSummaries") or [], "nextToken": data.get("nextToken")}
+    )
+
+
+def delete_recommendation(*, region: str, recommendation_id: str) -> DeleteRecommendationResult:
+    """Delete a recommendation; also stops an in-progress one (there is no separate Stop API)."""
+    data, _ = _signed_request(region=region, method="DELETE", path=f"/recommendations/{recommendation_id}")
+    return data

agentcore/aws/agui_parser.py

@@ -0,0 +1,131 @@
+"""Incremental AG-UI SSE stream parser (port of ``agui-parser.ts``).
+
+Upstream runs a background read loop that fans events out to two async consumers (a typed event
+stream and a text-only stream). This synchronous port keeps the same contract with a lazily-pulled
+shared buffer: whichever consumer runs ahead reads the next chunk from the source, and events are
+pruned once every active consumer has seen them. Consumers may be interleaved freely.
+"""
+
+from __future__ import annotations
+
+import codecs
+import re
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from agentcore.aws.agui_types import AguiEvent, AguiEventType, parse_agui_event
+
+if TYPE_CHECKING:
+    from agentcore.aws.agentcore import SSELogger
+
+_LINE_SPLIT = re.compile(r"\r?\n")
+
+
+@dataclass(slots=True)
+class AguiSSEStreams:
+    event_stream: Iterator[AguiEvent]
+    text_stream: Iterator[str] | None = None
+
+
+class _SharedEventBuffer:
+    def __init__(self, chunks: Iterable[bytes], logger: SSELogger | None, consumers: tuple[str, ...]):
+        self._source = iter(chunks)
+        self._logger = logger
+        self._decoder = codecs.getincrementaldecoder("utf-8")(errors="replace")
+        self._line_buffer = ""
+        self._events: list[AguiEvent] = []
+        self._offset = 0  # absolute index of self._events[0]
+        self._cursors = dict.fromkeys(consumers, 0)
+        self._done = False
+        self._error: BaseException | None = None
+
+    def _log(self, line: str) -> None:
+        if self._logger is not None:
+            self._logger.log_sse_event(line)
+
+    def _finish(self) -> None:
+        self._done = True
+        close = getattr(self._source, "close", None)
+        if close is not None:
+            try:
+                close()
+            except Exception:  # noqa: BLE001, S110 - already released
+                pass
+
+    def _pull(self) -> None:
+        try:
+            chunk = next(self._source)
+        except StopIteration:
+            if self._line_buffer.strip():
+                self._log(self._line_buffer)
+                event = parse_agui_event(self._line_buffer)
+                if event is not None:
+                    self._events.append(event)
+            self._line_buffer = ""
+            self._finish()
+            return
+        except Exception as exc:  # noqa: BLE001 - surfaced to consumers once drained
+            self._error = exc
+            self._finish()
+            return
+
+        self._line_buffer += self._decoder.decode(chunk)
+        lines = _LINE_SPLIT.split(self._line_buffer)
+        self._line_buffer = lines.pop()
+        for line in lines:
+            if line.strip():
+                self._log(line)
+            event = parse_agui_event(line)
+            if event is not None:
+                self._events.append(event)
+
+    def _prune(self) -> None:
+        min_cursor = min(self._cursors.values())
+        drop = min_cursor - self._offset
+        if drop > 0:
+            del self._events[:drop]
+            self._offset = min_cursor
+
+    def next_event(self, consumer: str) -> AguiEvent | None:
+        """Next event for ``consumer``; ``None`` at end of stream (raises a deferred read error)."""
+        while True:
+            index = self._cursors[consumer] - self._offset
+            if index < len(self._events):
+                event = self._events[index]
+                self._cursors[consumer] += 1
+                self._prune()
+                return event
+            if self._done:
+                if self._error is not None:
+                    raise self._error
+                return None
+            self._pull()
+
+
+def _js_str(value: Any) -> str:
+    return "undefined" if value is None else str(value)
+
+
+def parse_agui_sse_stream(
+    reader: Iterable[bytes], logger: SSELogger | None = None, single_consumer: bool = False
+) -> AguiSSEStreams:
+    """Split an SSE byte stream into AG-UI events (and, unless ``single_consumer``, text deltas)."""
+    consumers = ("events",) if single_consumer else ("events", "text")
+    shared = _SharedEventBuffer(reader, logger, consumers)
+
+    def event_stream() -> Iterator[AguiEvent]:
+        while (event := shared.next_event("events")) is not None:
+            yield event
+
+    def text_stream() -> Iterator[str]:
+        while (event := shared.next_event("text")) is not None:
+            event_type = event.get("type")
+            if event_type in (AguiEventType.TEXT_MESSAGE_CONTENT, AguiEventType.TEXT_MESSAGE_CHUNK):
+                delta = event.get("delta")
+                if delta:
+                    yield delta
+            elif event_type == AguiEventType.RUN_ERROR:
+                yield f"Error: {_js_str(event.get('message'))}"
+
+    return AguiSSEStreams(event_stream=event_stream(), text_stream=None if single_consumer else text_stream())