agentcore-cli 0.31.1__py3-none-any.whl

agentcore/lib/utils/env.py

@@ -0,0 +1,105 @@
+"""Read/write ``agentcore/.env.local`` with transparent at-rest encryption (port of ``env.ts``)."""
+
+from __future__ import annotations
+
+import os
+import re
+from collections.abc import Iterable, Mapping
+
+from agentcore.lib.constants import ENV_FILE
+from agentcore.lib.secrets import (
+    ENC_PREFIX,
+    decrypt_secret,
+    encrypt_secret,
+    is_sensitive_key,
+    resolve_candidate_keys,
+    resolve_encryption_key,
+)
+from agentcore.lib.utils.dotenv import parse as parse_dotenv
+
+_ENV_KEY_RE = re.compile(r"[a-z_][a-z0-9_]*", re.IGNORECASE)
+
+
+def get_env_path(config_root: str | None = None) -> str:
+    from agentcore.lib.schemas.io.path_resolver import find_config_root
+
+    root = config_root or find_config_root()
+    if not root:
+        raise RuntimeError("Could not find agentcore directory")
+    return os.path.join(root, ENV_FILE)
+
+
+def _serialize_env(env: Mapping[str, str | None]) -> str:
+    """Serialise to dotenv ``KEY="value"`` lines (same escaping as upstream)."""
+    lines = []
+    for k, v in env.items():
+        if v is None:
+            continue
+        if not _ENV_KEY_RE.fullmatch(k):
+            raise ValueError(f"Invalid env key: {k}")
+        val = str(v).replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n").replace("\r", "\\r")
+        lines.append(f'{k}="{val}"')
+    return "\n".join(lines) + "\n" if lines else ""
+
+
+def _read_raw(path: str) -> dict[str, str]:
+    with open(path, encoding="utf-8") as fh:
+        return parse_dotenv(fh.read())
+
+
+def _write(path: str, content: str) -> None:
+    with open(path, "w", encoding="utf-8", newline="") as fh:
+        fh.write(content)
+
+
+def read_env_file(config_root: str | None = None) -> dict[str, str]:
+    """Read ``.env.local``, decrypting ``enc:v1:`` values; legacy plaintext is returned as-is."""
+    path = get_env_path(config_root)
+    if not os.path.exists(path):
+        return {}
+    parsed = _read_raw(path)
+    if not any(v.startswith(ENC_PREFIX) for v in parsed.values()):
+        return parsed
+    # Try every available key so a value sealed by either source decrypts.
+    keys = resolve_candidate_keys()
+    return {k: decrypt_secret(v, keys) if v.startswith(ENC_PREFIX) else v for k, v in parsed.items()}
+
+
+def get_env_var(key: str, config_root: str | None = None) -> str | None:
+    return read_env_file(config_root).get(key)
+
+
+def _needs_encryption(k: str, v: str | None) -> bool:
+    return is_sensitive_key(k) and v is not None and not str(v).startswith(ENC_PREFIX)
+
+
+def _encrypt_sensitive(env: Mapping[str, str | None]) -> dict[str, str | None]:
+    """Encrypt sensitive plaintext values; leave others and already-encrypted values unchanged."""
+    if not any(_needs_encryption(k, v) for k, v in env.items()):
+        return dict(env)
+    key = resolve_encryption_key()
+    return {k: encrypt_secret(str(v), key) if _needs_encryption(k, v) else v for k, v in env.items()}
+
+
+def write_env_file(updates: Mapping[str, str | None], config_root: str | None = None, merge: bool = True) -> None:
+    """Write ``.env.local``, merging with existing values by default and encrypting secrets."""
+    path = get_env_path(config_root)
+    # Merge against the raw (still encrypted) values so unchanged secrets aren't re-encrypted.
+    current: dict[str, str | None] = dict(_read_raw(path)) if merge and os.path.exists(path) else {}
+    current.update(updates)
+    _write(path, _serialize_env(_encrypt_sensitive(current)))
+
+
+def set_env_var(key: str, value: str, config_root: str | None = None) -> None:
+    write_env_file({key: value}, config_root)
+
+
+def remove_env_vars(keys: Iterable[str], config_root: str | None = None) -> None:
+    path = get_env_path(config_root)
+    if not os.path.exists(path):
+        return
+    current: dict[str, str | None] = dict(_read_raw(path))
+    for key in keys:
+        current.pop(key, None)
+    # Re-encrypts any legacy plaintext among the remaining values.
+    _write(path, _serialize_env(_encrypt_sensitive(current)))

agentcore/lib/utils/json_format.py

@@ -0,0 +1,29 @@
+"""JSON serialisation matching ``JSON.stringify(value, null, indent)`` output."""
+
+from __future__ import annotations
+
+import json
+import math
+from typing import Any
+
+
+def _normalize(value: Any) -> Any:
+    # JS has a single number type: 1.0 serialises as "1"; NaN/Infinity become null.
+    if isinstance(value, float):
+        if math.isnan(value) or math.isinf(value):
+            return None
+        if value.is_integer() and abs(value) < 1e21:
+            return int(value)
+        return value
+    if isinstance(value, dict):
+        return {str(k): _normalize(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_normalize(v) for v in value]
+    return value
+
+
+def to_json_string(value: Any, indent: int | None = 2) -> str:
+    """Serialise like ``JSON.stringify(value, null, indent)`` (no trailing newline)."""
+    if indent is None:
+        return json.dumps(_normalize(value), ensure_ascii=False, separators=(",", ":"))
+    return json.dumps(_normalize(value), ensure_ascii=False, indent=indent)

agentcore/lib/utils/json_rpc.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def parse_json_rpc_response(text: str) -> dict[str, Any]:
+    """Parse a JSON-RPC response given as plain JSON or SSE-wrapped (``data: ...`` lines)."""
+    trimmed = text.strip()
+    try:
+        return json.loads(trimmed)
+    except ValueError:
+        pass  # might be SSE format
+
+    for line in reversed(trimmed.split("\n")):
+        if line.startswith("data: "):
+            try:
+                return json.loads(line[6:])
+            except ValueError:
+                continue
+
+    raise ValueError(f"Failed to parse JSON-RPC response: {trimmed[:200]}")

agentcore/lib/utils/platform.py

@@ -0,0 +1,33 @@
+"""Platform detection and cross-platform helpers (port of ``src/lib/utils/platform.ts``)."""
+
+from __future__ import annotations
+
+import os
+import sys
+
+is_windows = sys.platform == "win32"
+is_mac_os = sys.platform == "darwin"
+is_linux = sys.platform.startswith("linux")
+
+
+def get_venv_executable(venv_path: str, executable: str) -> str:
+    """Path to an executable in a Python venv (``bin/x`` on Unix, ``Scripts\\x.exe`` on Windows)."""
+    bin_dir = "Scripts" if is_windows else "bin"
+    ext = ".exe" if is_windows else ""
+    return os.path.join(venv_path, bin_dir, executable + ext)
+
+
+def get_shell_command() -> str:
+    return "cmd" if is_windows else os.environ.get("SHELL", "/bin/sh")
+
+
+def get_shell_args(command: str) -> list[str]:
+    return ["/c", command] if is_windows else ["-c", command]
+
+
+def normalize_command(command: str) -> str:
+    """Add ``.exe`` on Windows for well-known commands."""
+    if is_windows and not command.endswith((".exe", ".cmd", ".bat")):
+        if command.endswith(("python", "node", "npm", "git", "uvicorn", "pip")):
+            return command + ".exe"
+    return command

agentcore/lib/utils/polling.py

@@ -0,0 +1,86 @@
+"""Polling/retry utility (port of ``src/lib/utils/polling.ts``, synchronous)."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Generic, Literal, TypeVar
+
+from agentcore.lib.errors.types import PollExhaustedError, PollTimeoutError
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True, slots=True)
+class PollResult(Generic[T]):
+    done: bool
+    value: T | None = None
+
+
+def poll(
+    fn: Callable[[], PollResult[T]],
+    *,
+    max_attempts: int | None = None,
+    timeout_ms: float | None = None,
+    delay_ms: float = 5000,
+    backoff_factor: float = 1,
+    max_delay_ms: float | None = None,
+    max_consecutive_errors: int | None = None,
+    on_error: Callable[[BaseException], Literal["retry", "abort"]] | None = None,
+) -> T:
+    """Call ``fn`` until it reports ``done``; bounded by attempts and/or wall-clock timeout."""
+    if max_attempts is None and timeout_ms is None:
+        raise ValueError("poll() requires at least one of max_attempts or timeout_ms")
+
+    start = time.monotonic()
+    elapsed_ms = lambda: (time.monotonic() - start) * 1000  # noqa: E731
+    attempts = 0
+    consecutive_errors = 0
+    current_delay = delay_ms
+    last_error: BaseException | None = None
+
+    while True:
+        if max_attempts is not None and attempts >= max_attempts:
+            raise PollExhaustedError(max_attempts, cause=last_error)
+        if timeout_ms is not None and elapsed_ms() >= timeout_ms:
+            raise PollTimeoutError(timeout_ms, cause=last_error)
+
+        attempts += 1
+        try:
+            result = fn()
+            consecutive_errors = 0
+            if result.done:
+                return result.value  # type: ignore[return-value]
+        except Exception as exc:
+            if (on_error(exc) if on_error else "retry") == "abort":
+                raise
+            last_error = exc
+            consecutive_errors += 1
+            if max_consecutive_errors and consecutive_errors >= max_consecutive_errors:
+                raise PollExhaustedError(attempts, cause=last_error) from exc
+
+        # Don't sleep if that would cross the timeout.
+        if timeout_ms is not None and elapsed_ms() + current_delay >= timeout_ms:
+            raise PollTimeoutError(timeout_ms, cause=last_error)
+
+        time.sleep(current_delay / 1000)
+        current_delay = (
+            min(current_delay * backoff_factor, max_delay_ms) if max_delay_ms else current_delay * backoff_factor
+        )
+
+
+_THROTTLING_NAMES = {"ThrottlingException", "Throttling", "TooManyRequestsException", "RequestLimitExceeded"}
+
+
+def is_throttling_error(err: object) -> bool:
+    """True for AWS throttling/rate-limit errors (botocore ClientError codes or named exceptions)."""
+    if err is None:
+        return False
+    name = ""
+    response = getattr(err, "response", None)
+    if isinstance(response, dict):
+        name = str(response.get("Error", {}).get("Code", "") or "")
+    name = name or getattr(err, "name", "") or type(err).__name__
+    message = str(getattr(err, "message", "") or (err if isinstance(err, BaseException) else ""))
+    return name in _THROTTLING_NAMES or "Rate exceeded" in message or "Throttling" in message

agentcore/lib/utils/subprocess.py

@@ -0,0 +1,135 @@
+"""Subprocess helpers (port of ``src/lib/utils/subprocess.ts``).
+
+Nothing runs through a shell. Upstream uses cross-spawn to resolve Windows ``.cmd``/``.bat``
+shims; here ``shutil.which`` does the same resolution before ``subprocess`` runs the command.
+Upstream has async and sync variants; this port is synchronous only.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import signal as _signal
+import subprocess
+import sys
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from typing import IO, Any, Literal
+
+Stdio = Literal["inherit", "ignore", "pipe"] | int | IO[Any] | None
+
+
+@dataclass(frozen=True, slots=True)
+class SubprocessResult:
+    stdout: str
+    stderr: str
+    code: int | None
+    signal: str | None
+
+
+def _resolve(command: str) -> str:
+    if sys.platform == "win32":
+        return shutil.which(command) or command
+    return command
+
+
+def _stdio(value: Stdio) -> Any:
+    if value == "inherit":
+        return None
+    if value == "ignore":
+        return subprocess.DEVNULL
+    if value == "pipe":
+        return subprocess.PIPE
+    return value
+
+
+def _split_returncode(returncode: int) -> tuple[int | None, str | None]:
+    if returncode < 0:
+        try:
+            return None, _signal.Signals(-returncode).name
+        except ValueError:
+            return None, str(-returncode)
+    return returncode, None
+
+
+def _env(env: Mapping[str, str] | None) -> dict[str, str] | None:
+    return dict(env) if env is not None else None
+
+
+def run_subprocess(
+    command: str,
+    args: Sequence[str],
+    *,
+    cwd: str | os.PathLike[str] | None = None,
+    env: Mapping[str, str] | None = None,
+    stdio: Stdio = "inherit",
+) -> None:
+    """Run a command; raise ``RuntimeError`` on a non-zero exit (``OSError`` if it can't start)."""
+    proc = subprocess.run(
+        [_resolve(command), *args],
+        cwd=cwd,
+        env=_env(env),
+        stdin=_stdio(stdio),
+        stdout=_stdio(stdio),
+        stderr=_stdio(stdio),
+    )
+    if proc.returncode == 0:
+        return
+    code, sig = _split_returncode(proc.returncode)
+    reason = f"code {code}" if code is not None else f"signal {sig}"
+    raise RuntimeError(f"{command} exited with {reason}")
+
+
+def check_subprocess(
+    command: str,
+    args: Sequence[str],
+    *,
+    cwd: str | os.PathLike[str] | None = None,
+    env: Mapping[str, str] | None = None,
+    stdio: Stdio = "ignore",
+) -> bool:
+    """Return True iff the command starts and exits 0."""
+    try:
+        proc = subprocess.run(
+            [_resolve(command), *args],
+            cwd=cwd,
+            env=_env(env),
+            stdin=_stdio(stdio),
+            stdout=_stdio(stdio),
+            stderr=_stdio(stdio),
+        )
+    except OSError:
+        return False
+    return proc.returncode == 0
+
+
+def run_subprocess_capture(
+    command: str,
+    args: Sequence[str],
+    *,
+    cwd: str | os.PathLike[str] | None = None,
+    env: Mapping[str, str] | None = None,
+) -> SubprocessResult:
+    """Run with piped output; never raises. Spawn failures yield ``code=-1`` and the error in stderr."""
+    try:
+        proc = subprocess.run(
+            [_resolve(command), *args],
+            cwd=cwd,
+            env=_env(env),
+            stdin=subprocess.DEVNULL,
+            capture_output=True,
+        )
+    except OSError as exc:
+        return SubprocessResult(stdout="", stderr=str(exc), code=-1, signal=None)
+    code, sig = _split_returncode(proc.returncode)
+    return SubprocessResult(
+        stdout=proc.stdout.decode("utf-8", errors="replace"),
+        stderr=proc.stderr.decode("utf-8", errors="replace"),
+        code=code,
+        signal=sig,
+    )
+
+
+# Upstream keeps distinct *Sync variants for CDK bundling; in Python everything is synchronous.
+run_subprocess_capture_sync = run_subprocess_capture
+check_subprocess_sync = check_subprocess

agentcore/lib/utils/time_parser.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import re
+import time
+from datetime import UTC, datetime
+
+_RELATIVE_DURATION_RE = re.compile(r"(\d+)([smhd])")
+_UNIT_TO_MS = {"s": 1_000, "m": 60_000, "h": 3_600_000, "d": 86_400_000}
+_DATE_ONLY_RE = re.compile(r"\d{4}-\d{2}-\d{2}")
+
+
+def _now_ms() -> int:
+    return time.time_ns() // 1_000_000
+
+
+def parse_time_string(value: str) -> int:
+    """Parse a time string into epoch milliseconds.
+
+    Supports relative durations (``5m``, ``1h``, ``2d``, ``30s``, meaning "that long ago"),
+    ISO 8601, epoch milliseconds (13+ digits) and ``now``.
+    """
+    if not value or value.strip() == "":
+        raise ValueError("Time string cannot be empty")
+
+    trimmed = value.strip()
+    if trimmed == "now":
+        return _now_ms()
+
+    match = _RELATIVE_DURATION_RE.fullmatch(trimmed)
+    if match:
+        return _now_ms() - int(match.group(1)) * _UNIT_TO_MS[match.group(2)]
+
+    if re.fullmatch(r"\d{13,}", trimmed):
+        return int(trimmed)
+
+    try:
+        parsed = datetime.fromisoformat(trimmed)
+    except ValueError:
+        parsed = None
+    if parsed is not None:
+        # Like JS Date: date-only forms are UTC; date-times without an offset are local time.
+        if parsed.tzinfo is None and _DATE_ONLY_RE.fullmatch(trimmed):
+            parsed = parsed.replace(tzinfo=UTC)
+        return int(parsed.timestamp() * 1000)
+
+    raise ValueError(
+        f'Invalid time string: "{value}". Use relative durations (5m, 1h, 2d), ISO 8601, epoch ms, or "now".'
+    )

agentcore/lib/utils/validation.py

@@ -0,0 +1,106 @@
+"""Schema validation helpers (port of ``src/lib/utils/zod.ts`` for Pydantic models)."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from functools import lru_cache
+from typing import Any
+
+from pydantic import BaseModel, TypeAdapter
+from pydantic import ValidationError as PydanticValidationError
+
+_ABSENT: Any = object()
+
+
+@lru_cache(maxsize=512)
+def _field_adapter(model: type[BaseModel], name: str) -> TypeAdapter[Any]:
+    from typing import Annotated
+
+    info = model.model_fields[name]
+    annotation = info.annotation
+    if info.metadata:
+        annotation = Annotated[(annotation, *info.metadata)]  # type: ignore[valid-type]
+    return TypeAdapter(annotation)
+
+
+def _nested_model(annotation: Any) -> type[BaseModel] | None:
+    """Unwrap Optional/Union-with-None to a single BaseModel type, if that's what it is."""
+    import types
+    import typing
+
+    if isinstance(annotation, type) and issubclass(annotation, BaseModel):
+        return annotation
+    if typing.get_origin(annotation) in (typing.Union, types.UnionType):
+        args = [a for a in typing.get_args(annotation) if a is not type(None)]
+        if len(args) == 1:
+            return _nested_model(args[0])
+    return None
+
+
+def resilient_parse(
+    model: type[BaseModel],
+    data: Any,
+    *,
+    fallback: Any = _ABSENT,
+    fill_missing: bool = False,
+    keep_unknown: bool = True,
+) -> dict[str, Any]:
+    """Validate ``data`` against ``model`` field by field; invalid fields fall back instead of raising.
+
+    Keys use the field's alias (the on-disk JSON name). Nested models are parsed recursively.
+    With the default ``fallback`` (upstream's ``undefined``), invalid or missing fields are
+    simply omitted from the result.
+    """
+    if not isinstance(data, Mapping):
+        return {}
+    result: dict[str, Any] = {}
+    known: set[str] = set()
+    for name, info in model.model_fields.items():
+        key = info.alias or name
+        known.add(key)
+        if key not in data:
+            if fill_missing and fallback is not _ABSENT:
+                result[key] = fallback
+            continue
+        value = data[key]
+        nested = _nested_model(info.annotation)
+        if nested is not None and isinstance(value, Mapping):
+            result[key] = resilient_parse(
+                nested, value, fallback=fallback, fill_missing=fill_missing, keep_unknown=keep_unknown
+            )
+            continue
+        try:
+            adapter = _field_adapter(model, name)
+            result[key] = adapter.dump_python(adapter.validate_python(value), mode="json", by_alias=True)
+        except PydanticValidationError:
+            if fallback is not _ABSENT:
+                result[key] = fallback
+    if keep_unknown:
+        for key, value in data.items():
+            if key not in known:
+                result[key] = value
+    return result
+
+
+def _issues_message(exc: PydanticValidationError) -> str:
+    return "; ".join(f"{'.'.join(str(p) for p in e['loc'])}: {e['msg']}" for e in exc.errors())
+
+
+def validate_agent_schema(spec: Any) -> Any:
+    """Validate an agent spec; raises ``ValueError("Invalid AgentEnvSpec: ...")``."""
+    from agentcore.schema import AgentEnvSpec  # type: ignore[attr-defined]
+
+    try:
+        return AgentEnvSpec.model_validate(spec)
+    except PydanticValidationError as exc:
+        raise ValueError(f"Invalid AgentEnvSpec: {_issues_message(exc)}") from exc
+
+
+def validate_project_schema(spec: Any) -> Any:
+    """Validate a project spec; raises ``ValueError("Invalid AgentCoreProjectSpec: ...")``."""
+    from agentcore.schema import AgentCoreProjectSpec  # type: ignore[attr-defined]
+
+    try:
+        return AgentCoreProjectSpec.model_validate(spec)
+    except PydanticValidationError as exc:
+        raise ValueError(f"Invalid AgentCoreProjectSpec: {_issues_message(exc)}") from exc

agentcore/logging/__init__.py

@@ -0,0 +1,10 @@
+"""CLI loggers (port of upstream ``src/cli/logging``)."""
+
+from agentcore.logging.cdk_io_host import create_cdk_io_host
+from agentcore.logging.create_logger import CreateLogger
+from agentcore.logging.dev_logger import DevLogger
+from agentcore.logging.exec_logger import ExecLogger
+from agentcore.logging.invoke_logger import InvokeLogger
+from agentcore.logging.remove_logger import RemoveLogger
+
+__all__ = ["CreateLogger", "DevLogger", "ExecLogger", "InvokeLogger", "RemoveLogger", "create_cdk_io_host"]

agentcore/logging/_common.py

@@ -0,0 +1,77 @@
+"""Formatting helpers shared by the CLI loggers (duplicated per class upstream)."""
+
+import json
+import os
+import re
+import time
+from datetime import UTC, datetime
+from typing import Any
+
+ANSI_REGEX = re.compile(r"\x1b\[[0-9;]*[a-zA-Z]")
+
+
+def strip_ansi(s: str) -> str:
+    return ANSI_REGEX.sub("", s)
+
+
+def now_ms() -> int:
+    return int(time.time() * 1000)
+
+
+def format_timestamp_for_filename(date: datetime) -> str:
+    """YYYYMMDD-HHMMSS in local time."""
+    return date.strftime("%Y%m%d-%H%M%S")
+
+
+def format_time(date: datetime | None = None, with_ms: bool = False) -> str:
+    """HH:MM:SS (or HH:MM:SS.mmm) in local time."""
+    date = date or datetime.now()
+    text = date.strftime("%H:%M:%S")
+    return f"{text}.{date.microsecond // 1000:03d}" if with_ms else text
+
+
+def iso_now(date: datetime | None = None) -> str:
+    """JavaScript ``Date.toISOString()``: UTC with millisecond precision and a ``Z`` suffix."""
+    date = (date or datetime.now()).astimezone(UTC)
+    return date.strftime("%Y-%m-%dT%H:%M:%S.") + f"{date.microsecond // 1000:03d}Z"
+
+
+def format_duration(ms: int) -> str:
+    if ms < 1000:
+        return f"{ms}ms"
+    seconds = ms / 1000
+    if seconds < 60:
+        return f"{seconds:.1f}s"
+    minutes = int(seconds // 60)
+    remaining = round(seconds % 60)
+    return f"{minutes}m {remaining}s"
+
+
+def osc8_link(file_path: str) -> str:
+    url = f"file://{file_path}"
+    display = os.path.relpath(file_path, os.getcwd())
+    return f"\x1b]8;;{url}\x1b\\{display}\x1b]8;;\x1b\\"
+
+
+def append(file_path: str, text: str) -> None:
+    with open(file_path, "a", encoding="utf-8") as f:
+        f.write(text)
+
+
+def write(file_path: str, text: str) -> None:
+    with open(file_path, "w", encoding="utf-8") as f:
+        f.write(text)
+
+
+def js_json(value: Any, indent: int | None = 2) -> str:
+    """``JSON.stringify(value, null, indent)`` with ``None`` values in dicts treated as undefined."""
+
+    def clean(v: Any) -> Any:
+        if isinstance(v, dict):
+            return {k: clean(x) for k, x in v.items() if x is not None}
+        if isinstance(v, (list, tuple)):
+            return [clean(x) for x in v]
+        return v
+
+    separators = (",", ":") if indent is None else None
+    return json.dumps(clean(value), indent=indent, separators=separators, ensure_ascii=False, default=str)