agentcore-cli 0.31.1__py3-none-any.whl

agentcore/aws/shell_framer.py

@@ -0,0 +1,136 @@
+"""Channel-prefixed binary framing for interactive shells (port of ``shell-framer.ts``).
+
+Wire format: a 1-byte channel ID followed by payload bytes (identical to k8s
+``v5.channel.k8s.io``). Oversized stdin payloads raise the builtin :class:`ValueError`, which plays
+the role of upstream's local ``ValueError`` class.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from enum import IntEnum
+from typing import Any, Literal, NotRequired, TypedDict
+
+MAX_FRAME_SIZE = 65536
+
+
+class ShellChannel(IntEnum):
+    STDIN = 0x00
+    STDOUT = 0x01
+    STDERR = 0x02
+    STATUS = 0x03
+    RESIZE = 0x04
+    HEARTBEAT = 0x05
+    CLOSE = 0xFF
+
+
+@dataclass(frozen=True, slots=True)
+class ShellFrame:
+    channel: ShellChannel | int
+    """Channel byte; unknown channels are passed through as plain ints."""
+    payload: bytes
+
+    @property
+    def text(self) -> str:
+        """UTF-8 text of the payload."""
+        return self.payload.decode("utf-8", errors="replace")
+
+    def json(self) -> Any:
+        """Parse the payload as JSON (raises ``ValueError`` on invalid JSON)."""
+        return json.loads(self.payload.decode("utf-8", errors="replace"))
+
+
+def _channel(value: int) -> ShellChannel | int:
+    try:
+        return ShellChannel(value)
+    except ValueError:
+        return value
+
+
+class ShellFramer:
+    """Stateless encoder/decoder for the shell framing protocol."""
+
+    def decode(self, raw: bytes) -> ShellFrame:
+        if len(raw) == 0:
+            raise ValueError("Empty frame")
+        return ShellFrame(channel=_channel(raw[0]), payload=bytes(raw[1:]))
+
+    def encode_stdin(self, text: str) -> bytes:
+        return self.encode_stdin_raw(text.encode("utf-8"))
+
+    def encode_stdin_raw(self, chunk: bytes) -> bytes:
+        """Encode raw bytes (ESC sequences, arrow keys, non-UTF-8 input) as a STDIN frame."""
+        if len(chunk) > MAX_FRAME_SIZE:
+            raise ValueError(
+                f"stdin payload {len(chunk)} bytes exceeds MAX_FRAME_SIZE {MAX_FRAME_SIZE}; chunk large pastes"
+            )
+        return bytes([ShellChannel.STDIN]) + bytes(chunk)
+
+    def encode_resize(self, cols: int, rows: int) -> bytes:
+        payload = json.dumps({"width": cols, "height": rows}, separators=(",", ":")).encode("utf-8")
+        return bytes([ShellChannel.RESIZE]) + payload
+
+    def encode_heartbeat(self) -> bytes:
+        return bytes([ShellChannel.HEARTBEAT])
+
+
+# --- STATUS frame parsing ---
+
+
+class StatusConfirmation(TypedDict):
+    type: Literal["confirmation"]
+    shellId: str
+    reconnected: bool
+    bytesDropped: NotRequired[int]
+
+
+class StatusTermination(TypedDict):
+    type: Literal["termination"]
+    exitCode: int | None
+    signal: str | None
+
+
+class StatusUnknown(TypedDict):
+    type: Literal["unknown"]
+
+
+StatusFrameResult = StatusConfirmation | StatusTermination | StatusUnknown
+
+_LEADING_INT = re.compile(r"^\s*([+-]?\d+)")
+
+
+def _parse_int(value: str) -> int | None:
+    # JS parseInt(value, 10): leading integer prefix, NaN (-> None) otherwise.
+    match = _LEADING_INT.match(value)
+    return int(match.group(1)) if match else None
+
+
+def parse_status_frame(frame: ShellFrame) -> StatusFrameResult:
+    """Classify a STATUS frame: confirmation frames carry ``metadata.shellId``; termination frames don't."""
+    try:
+        status = frame.json()
+    except ValueError:
+        return {"type": "unknown"}
+    if not isinstance(status, dict):
+        status = {}
+
+    metadata = status.get("metadata") if isinstance(status.get("metadata"), dict) else {}
+    shell_id = metadata.get("shellId")
+    if shell_id:
+        result: StatusConfirmation = {
+            "type": "confirmation",
+            "shellId": shell_id,
+            "reconnected": metadata.get("reconnected") if metadata.get("reconnected") is not None else False,
+        }
+        if "bytesDropped" in metadata and metadata["bytesDropped"] is not None:
+            result["bytesDropped"] = metadata["bytesDropped"]
+        return result
+
+    details = status.get("details") if isinstance(status.get("details"), dict) else {}
+    causes = details.get("causes") or []
+    exit_code_str = next((c.get("message") for c in causes if c.get("reason") == "ExitCode"), None)
+    signal = next((c.get("message") for c in causes if c.get("reason") == "Signal"), None)
+    exit_code = _parse_int(str(exit_code_str)) if exit_code_str is not None else None
+    return {"type": "termination", "exitCode": exit_code, "signal": signal}

agentcore/aws/stage_endpoint.py

@@ -0,0 +1,39 @@
+"""AgentCore endpoint resolution with ``AGENTCORE_STAGE`` overrides (port of ``stage-endpoint.ts``).
+
+Set ``AGENTCORE_STAGE=beta|gamma`` to target pre-release environments.
+"""
+
+from __future__ import annotations
+
+import os
+
+from agentcore.aws.partition import dns_suffix
+
+
+def _stage() -> str | None:
+    stage = os.environ.get("AGENTCORE_STAGE")
+    return stage.lower() if stage is not None else None
+
+
+def is_prerelease_stage() -> bool:
+    return _stage() in ("beta", "gamma")
+
+
+def data_plane_endpoint(region: str) -> str:
+    """HTTPS endpoint of the ``bedrock-agentcore`` data plane (``elcapdp`` in pre-release)."""
+    stage = _stage()
+    if stage == "beta":
+        return f"https://beta.{region}.elcapdp.genesis-primitives.aws.dev"
+    if stage == "gamma":
+        return f"https://gamma.{region}.elcapdp.genesis-primitives.aws.dev"
+    return f"https://bedrock-agentcore.{region}.{dns_suffix(region)}"
+
+
+def control_plane_endpoint(region: str) -> str:
+    """HTTPS endpoint of the ``bedrock-agentcore-control`` plane (``elcapcp`` in pre-release)."""
+    stage = _stage()
+    if stage == "beta":
+        return f"https://beta.{region}.elcapcp.genesis-primitives.aws.dev"
+    if stage == "gamma":
+        return f"https://gamma.{region}.elcapcp.genesis-primitives.aws.dev"
+    return f"https://bedrock-agentcore-control.{region}.{dns_suffix(region)}"

agentcore/aws/target_region.py

@@ -0,0 +1,54 @@
+"""Make a deployment target's region authoritative for downstream AWS calls (port of ``target-region.ts``).
+
+boto3 (and the CDK toolkit subprocess) resolve region from ``AWS_REGION`` / ``AWS_DEFAULT_REGION``
+when no explicit region is given. ``aws-targets.json`` is the source of truth, so the target's
+region is promoted onto the environment for the operation and the previous values restored after.
+See https://github.com/aws/agentcore-cli/issues/924.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from typing import TypeVar
+
+T = TypeVar("T")
+
+RestoreEnv = Callable[[], None]
+
+
+def apply_target_region_to_env(region: str) -> RestoreEnv:
+    """Set ``AWS_REGION``/``AWS_DEFAULT_REGION`` to ``region``; returns a function that restores them."""
+    prev_region = os.environ.get("AWS_REGION")
+    prev_default_region = os.environ.get("AWS_DEFAULT_REGION")
+    os.environ["AWS_REGION"] = region
+    os.environ["AWS_DEFAULT_REGION"] = region
+
+    def restore() -> None:
+        for key, prev in (("AWS_REGION", prev_region), ("AWS_DEFAULT_REGION", prev_default_region)):
+            if prev is None:
+                os.environ.pop(key, None)
+            else:
+                os.environ[key] = prev
+
+    return restore
+
+
+def with_target_region(region: str, fn: Callable[[], T]) -> T:
+    """Run ``fn`` with ``region`` applied to the environment, restoring prior values afterwards."""
+    restore = apply_target_region_to_env(region)
+    try:
+        return fn()
+    finally:
+        restore()
+
+
+@contextmanager
+def target_region(region: str) -> Iterator[None]:
+    """Context-manager form of :func:`with_target_region`."""
+    restore = apply_target_region_to_env(region)
+    try:
+        yield
+    finally:
+        restore()

agentcore/aws/transaction_search.py

@@ -0,0 +1,97 @@
+"""Enable CloudWatch Transaction Search (port of ``transaction-search.ts``)."""
+
+from __future__ import annotations
+
+from agentcore.aws._aws_errors import get_error_message, is_access_denied_error
+from agentcore.aws.account import create_aws_client
+from agentcore.aws.partition import arn_prefix
+from agentcore.lib.errors.types import AccessDeniedError
+from agentcore.lib.result import Result, err, ok
+from agentcore.lib.utils.json_format import to_json_string
+
+RESOURCE_POLICY_NAME = "TransactionSearchXRayAccess"
+
+
+def _failure(exc: Exception, access_denied_prefix: str, generic_prefix: str) -> Result:
+    message = get_error_message(exc)
+    if is_access_denied_error(exc):
+        return err(AccessDeniedError(f"{access_denied_prefix}: {message}", cause=exc))
+    error = RuntimeError(f"{generic_prefix}: {message}")
+    error.__cause__ = exc
+    return err(error)
+
+
+def enable_transaction_search(region: str, account_id: str, index_percentage: float = 100) -> Result:
+    """Idempotently enable Transaction Search; safe to call on every deploy.
+
+    1. Start Application Signals discovery.
+    2. Create the CloudWatch Logs resource policy for X-Ray (if missing).
+    3. Route trace segments to CloudWatch Logs.
+    4. Index ``index_percentage`` % of spans on the built-in ``Default`` rule.
+    """
+    # Step 1: Application Signals (creates the service-linked role).
+    try:
+        create_aws_client("application-signals", region).start_discovery()
+    except Exception as exc:  # noqa: BLE001
+        return _failure(
+            exc, "Insufficient permissions to enable Application Signals", "Failed to enable Application Signals"
+        )
+
+    # Step 2: CloudWatch Logs resource policy for X-Ray.
+    try:
+        logs = create_aws_client("logs", region)
+        policies = logs.describe_resource_policies().get("resourcePolicies") or []
+        if not any(p.get("policyName") == RESOURCE_POLICY_NAME for p in policies):
+            prefix = arn_prefix(region)
+            policy_document = to_json_string(
+                {
+                    "Version": "2012-10-17",
+                    "Statement": [
+                        {
+                            "Sid": "TransactionSearchXRayAccess",
+                            "Effect": "Allow",
+                            "Principal": {"Service": "xray.amazonaws.com"},
+                            "Action": "logs:PutLogEvents",
+                            "Resource": [
+                                f"{prefix}:logs:{region}:{account_id}:log-group:aws/spans:*",
+                                f"{prefix}:logs:{region}:{account_id}:log-group:/aws/application-signals/data:*",
+                            ],
+                            "Condition": {
+                                "ArnLike": {"aws:SourceArn": f"{prefix}:xray:{region}:{account_id}:*"},
+                                "StringEquals": {"aws:SourceAccount": account_id},
+                            },
+                        }
+                    ],
+                },
+                indent=None,
+            )
+            logs.put_resource_policy(policyName=RESOURCE_POLICY_NAME, policyDocument=policy_document)
+    except Exception as exc:  # noqa: BLE001
+        return _failure(
+            exc,
+            "Insufficient permissions to configure CloudWatch Logs policy",
+            "Failed to configure CloudWatch Logs policy",
+        )
+
+    xray = create_aws_client("xray", region)
+
+    # Step 3: trace segment destination.
+    try:
+        if xray.get_trace_segment_destination().get("Destination") != "CloudWatchLogs":
+            xray.update_trace_segment_destination(Destination="CloudWatchLogs")
+    except Exception as exc:  # noqa: BLE001
+        return _failure(
+            exc, "Insufficient permissions to configure trace destination", "Failed to configure trace destination"
+        )
+
+    # Step 4: indexing on the built-in Default rule (always exists).
+    try:
+        xray.update_indexing_rule(
+            Name="Default", Rule={"Probabilistic": {"DesiredSamplingPercentage": index_percentage}}
+        )
+    except Exception as exc:  # noqa: BLE001
+        return _failure(
+            exc, "Insufficient permissions to configure indexing rules", "Failed to configure indexing rules"
+        )
+
+    return ok()

agentcore/cdk/__init__.py

@@ -0,0 +1,10 @@
+"""The vended CDK project (port of upstream ``src/cli/cdk``).
+
+Only the project-management part is ported here. Upstream's ``toolkit-lib/`` wraps the JavaScript
+``@aws-cdk/toolkit-lib`` API (synth/deploy/diff/destroy) and belongs with deploy orchestration.
+"""
+
+from agentcore.cdk.constants import CDK_APP_ENTRY, CDK_PROJECT_DIR
+from agentcore.cdk.local_cdk_project import LocalCdkProject
+
+__all__ = ["CDK_APP_ENTRY", "CDK_PROJECT_DIR", "LocalCdkProject"]

agentcore/cdk/constants.py

@@ -0,0 +1,13 @@
+"""CDK project location constants (from upstream ``src/cli/constants.ts``)."""
+
+from __future__ import annotations
+
+from typing import Final
+
+# Directory of the CDK project generated by `agentcore create`, relative to CONFIG_DIR (agentcore/cdk/).
+CDK_PROJECT_DIR: Final = "cdk"
+
+# CDK app entry point relative to the CDK project directory (the compiled JS in dist/).
+CDK_APP_ENTRY: Final = "dist/bin/cdk.js"
+
+__all__ = ["CDK_APP_ENTRY", "CDK_PROJECT_DIR"]

agentcore/cdk/local_cdk_project.py

@@ -0,0 +1,48 @@
+"""The local CDK project vended by `agentcore create` (port of ``local-cdk-project.ts``)."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from agentcore.cdk.constants import CDK_PROJECT_DIR
+from agentcore.lib import CONFIG_DIR, run_subprocess_capture
+
+
+class LocalCdkProject:
+    """Validates, installs, and builds the CDK project at ``<base_dir>/agentcore/cdk``."""
+
+    def __init__(self, base_dir: str | os.PathLike[str] | None = None) -> None:
+        self.project_dir = Path(base_dir if base_dir is not None else os.getcwd()) / CONFIG_DIR / CDK_PROJECT_DIR
+
+    @classmethod
+    def from_path(cls, project_dir: str | os.PathLike[str]) -> LocalCdkProject:
+        """Create from an explicit CDK project directory."""
+        instance = cls.__new__(cls)
+        instance.project_dir = Path(project_dir)
+        return instance
+
+    def exists(self) -> bool:
+        return self.project_dir.exists() and (self.project_dir / "package.json").exists()
+
+    def validate(self) -> None:
+        """Raise if the project is missing or has no package.json."""
+        if not self.project_dir.exists():
+            raise FileNotFoundError(f"CDK project not found at {self.project_dir}. Run 'agentcore create' first.")
+        if not (self.project_dir / "package.json").exists():
+            raise FileNotFoundError(f"Invalid CDK project: missing package.json in {self.project_dir}")
+
+    def install(self) -> None:
+        """Run ``npm install``."""
+        result = run_subprocess_capture("npm", ["install"], cwd=self.project_dir)
+        if result.code != 0:
+            raise RuntimeError(result.stderr or result.stdout or f"npm exited with code {result.code}")
+
+    def build(self) -> None:
+        """Compile the TypeScript project (``npm run build``)."""
+        result = run_subprocess_capture("npm", ["run", "build"], cwd=self.project_dir)
+        if result.code != 0:
+            raise RuntimeError(result.stderr or result.stdout or f"npm run build exited with code {result.code}")
+
+
+__all__ = ["LocalCdkProject"]