agentcore-cli 0.31.1__py3-none-any.whl

agentcore/lib/schemas/io/path_resolver.py

@@ -0,0 +1,132 @@
+"""Project discovery and AgentCore file paths (port of ``path-resolver.ts``)."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from agentcore.lib.constants import APP_DIR, CLI_LOGS_DIR, CLI_SYSTEM_DIR, CONFIG_DIR, CONFIG_FILES
+from agentcore.lib.errors.types import NoProjectError
+
+__all__ = [
+    "CONFIG_FILES",
+    "PathConfig",
+    "PathResolver",
+    "default_path_config",
+    "find_config_root",
+    "find_project_root",
+    "get_session_project_root",
+    "get_working_directory",
+    "require_config_root",
+    "set_session_project_root",
+]
+
+
+def get_working_directory() -> str:
+    """Directory the user invoked the CLI from (``INIT_CWD`` when launched via an npm script)."""
+    return os.environ.get("INIT_CWD") or os.getcwd()
+
+
+_session_project_root: str | None = None
+
+
+def set_session_project_root(project_root: str | None) -> None:
+    """Set the project root for this session (after ``create``) so discovery checks it first."""
+    global _session_project_root
+    _session_project_root = os.fspath(project_root) if project_root is not None else None
+
+
+def get_session_project_root() -> str | None:
+    return _session_project_root
+
+
+@dataclass(slots=True)
+class PathConfig:
+    """Where AgentCore files are stored: ``base_dir`` is the ``agentcore/`` directory."""
+
+    base_dir: str
+
+
+def _is_valid_config_dir(config_path: str) -> bool:
+    return os.path.exists(os.path.join(config_path, CONFIG_FILES.AGENT_ENV))
+
+
+def find_config_root(start_dir: str | None = None) -> str | None:
+    """Walk up from ``start_dir`` to the nearest ``agentcore/`` dir containing ``agentcore.json``."""
+    if _session_project_root:
+        session_config = os.path.join(_session_project_root, CONFIG_DIR)
+        if os.path.exists(session_config) and _is_valid_config_dir(session_config):
+            return session_config
+
+    current = os.fspath(start_dir) if start_dir is not None else get_working_directory()
+    while True:
+        config_path = os.path.join(current, CONFIG_DIR)
+        if os.path.exists(config_path) and _is_valid_config_dir(config_path):
+            return config_path
+        parent = os.path.dirname(current)
+        if parent == current:
+            return None
+        current = parent
+
+
+def require_config_root(start_dir: str | None = None) -> str:
+    root = find_config_root(start_dir)
+    if not root:
+        raise NoProjectError()
+    return root
+
+
+def find_project_root(start_dir: str | None = None) -> str | None:
+    """The project root (parent of ``agentcore/``), or ``None``."""
+    config_root = find_config_root(start_dir if start_dir is not None else os.getcwd())
+    return os.path.dirname(config_root) if config_root else None
+
+
+def default_path_config() -> PathConfig:
+    """Default: ``agentcore/`` under the working directory."""
+    return PathConfig(base_dir=os.path.join(get_working_directory(), CONFIG_DIR))
+
+
+class PathResolver:
+    def __init__(self, config: PathConfig | None = None, *, base_dir: str | None = None):
+        resolved = base_dir or (config.base_dir if config else None)
+        self._config = PathConfig(base_dir=os.fspath(resolved) if resolved else default_path_config().base_dir)
+
+    def get_base_dir(self) -> str:
+        return self._config.base_dir
+
+    def get_project_root(self) -> str:
+        return os.path.dirname(self._config.base_dir)
+
+    def get_agent_config_path(self) -> str:
+        return os.path.join(self._config.base_dir, CONFIG_FILES.AGENT_ENV)
+
+    def get_aws_targets_config_path(self) -> str:
+        return os.path.join(self._config.base_dir, CONFIG_FILES.AWS_TARGETS)
+
+    def get_cli_system_dir(self) -> str:
+        return os.path.join(self._config.base_dir, CLI_SYSTEM_DIR)
+
+    def get_logs_dir(self) -> str:
+        return os.path.join(self._config.base_dir, CLI_SYSTEM_DIR, CLI_LOGS_DIR)
+
+    def get_invoke_logs_dir(self) -> str:
+        return os.path.join(self._config.base_dir, CLI_SYSTEM_DIR, CLI_LOGS_DIR, "invoke")
+
+    def get_state_path(self) -> str:
+        return os.path.join(self._config.base_dir, CLI_SYSTEM_DIR, CONFIG_FILES.DEPLOYED_STATE)
+
+    def get_mcp_defs_path(self) -> str:
+        return os.path.join(self._config.base_dir, CONFIG_FILES.MCP_DEFS)
+
+    def get_harnesses_dir(self) -> str:
+        return os.path.join(self.get_project_root(), APP_DIR)
+
+    def get_harness_dir(self, harness_name: str) -> str:
+        return os.path.join(self.get_project_root(), APP_DIR, harness_name)
+
+    def get_harness_config_path(self, harness_name: str) -> str:
+        return os.path.join(self.get_project_root(), APP_DIR, harness_name, "harness.json")
+
+    def set_base_dir(self, base_dir: str) -> None:
+        self._config.base_dir = os.fspath(base_dir)

agentcore/lib/secrets/__init__.py

@@ -0,0 +1,18 @@
+from agentcore.lib.secrets.cipher import ENC_PREFIX, decrypt_secret, encrypt_secret
+from agentcore.lib.secrets.key_provider import resolve_candidate_keys, resolve_encryption_key
+from agentcore.lib.secrets.sensitive_keys import (
+    SENSITIVE_KEY_PATTERNS,
+    is_sensitive_key,
+    validate_credential_name_encryptable,
+)
+
+__all__ = [
+    "ENC_PREFIX",
+    "SENSITIVE_KEY_PATTERNS",
+    "decrypt_secret",
+    "encrypt_secret",
+    "is_sensitive_key",
+    "resolve_candidate_keys",
+    "resolve_encryption_key",
+    "validate_credential_name_encryptable",
+]

agentcore/lib/secrets/cipher.py

@@ -0,0 +1,70 @@
+"""AES-256-GCM envelope for secrets at rest (port of ``src/lib/secrets/cipher.ts``).
+
+Envelope: ``enc:v1:`` + base64(IV[12] || tag[16] || ciphertext). ``cryptography``'s AESGCM
+emits ciphertext || tag, so the tag is moved to sit right after the IV to match Node.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import os
+from collections.abc import Sequence
+
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+from agentcore.lib.errors.types import SecretDecryptionError
+
+ENC_PREFIX = "enc:v1:"
+
+IV_BYTES = 12
+TAG_BYTES = 16
+
+
+def encrypt_secret(plaintext: str, key: bytes) -> str:
+    """Encrypt a plaintext secret to an ``enc:v1:`` envelope."""
+    iv = os.urandom(IV_BYTES)
+    sealed = AESGCM(key).encrypt(iv, plaintext.encode("utf-8"), None)
+    ciphertext, tag = sealed[:-TAG_BYTES], sealed[-TAG_BYTES:]
+    return ENC_PREFIX + base64.b64encode(iv + tag + ciphertext).decode("ascii")
+
+
+def _b64decode_lenient(data: str) -> bytes:
+    # Node's Buffer.from(..., 'base64') tolerates missing padding and stray characters.
+    cleaned = "".join(c for c in data if c.isalnum() or c in "+/-_")
+    cleaned = cleaned.replace("-", "+").replace("_", "/")
+    return base64.b64decode(cleaned + "=" * (-len(cleaned) % 4))
+
+
+def _try_decrypt(token: str, key: bytes) -> str | None:
+    """Decrypt with one key; ``None`` on any failure."""
+    try:
+        raw = _b64decode_lenient(token[len(ENC_PREFIX) :])
+        iv = raw[:IV_BYTES]
+        tag = raw[IV_BYTES : IV_BYTES + TAG_BYTES]
+        ciphertext = raw[IV_BYTES + TAG_BYTES :]
+        if len(iv) != IV_BYTES or len(tag) != TAG_BYTES:
+            return None
+        return AESGCM(key).decrypt(iv, ciphertext + tag, None).decode("utf-8")
+    except (InvalidTag, ValueError, TypeError, binascii.Error, UnicodeDecodeError):
+        return None
+
+
+def decrypt_secret(token: str, keys: bytes | Sequence[bytes]) -> str:
+    """Decrypt an ``enc:v1:`` envelope, trying each candidate key in turn.
+
+    A value may have been sealed by the keychain key or the keyfile key; trying all keys lets
+    it decrypt even if the active key source changed since it was written.
+    """
+    if not token.startswith(ENC_PREFIX):
+        raise SecretDecryptionError("Value is not an encrypted secret envelope.")
+    candidates = [keys] if isinstance(keys, (bytes, bytearray)) else list(keys)
+    for key in candidates:
+        plaintext = _try_decrypt(token, bytes(key))
+        if plaintext is not None:
+            return plaintext
+    raise SecretDecryptionError(
+        "Could not decrypt a stored secret in agentcore/.env.local — the encryption key may be missing or changed. "
+        "Re-add the credential"
+    )

agentcore/lib/secrets/key_provider.py

@@ -0,0 +1,163 @@
+"""Machine encryption key resolution (port of ``src/lib/secrets/key-provider.ts``).
+
+Encryption key: OS keychain (service ``aws-agentcore``, account ``env-local-secret-key``,
+base64-encoded 32 bytes) unless ``AGENTCORE_DISABLE_KEYCHAIN=1``, else the keyfile
+``$AGENTCORE_CONFIG_DIR/secrets.key`` (default ``~/.agentcore/secrets.key``, raw 32 bytes, 0600).
+Decryption tries every key that exists, without creating any.
+"""
+
+from __future__ import annotations
+
+import base64
+import os
+import sys
+from pathlib import Path
+
+from agentcore.lib.errors.types import SecretEncryptionError
+
+KEY_BYTES = 32
+KEYCHAIN_SERVICE = "aws-agentcore"
+KEYCHAIN_ACCOUNT = "env-local-secret-key"
+
+_cached_key: bytes | None = None
+
+
+def _keychain_disabled() -> bool:
+    return os.environ.get("AGENTCORE_DISABLE_KEYCHAIN") == "1"
+
+
+def _keychain_service() -> str:
+    # @napi-rs/keyring (keyring-rs) stores Windows credentials under the target name
+    # "<account>.<service>"; Python keyring's Windows backend uses the service name as the
+    # target, so pass the keyring-rs target to address the same credential.
+    if sys.platform == "win32":
+        return f"{KEYCHAIN_ACCOUNT}.{KEYCHAIN_SERVICE}"
+    return KEYCHAIN_SERVICE
+
+
+def _b64decode(value: str) -> bytes:
+    return base64.b64decode(value + "=" * (-len(value) % 4))
+
+
+def _try_keychain_key() -> bytes | None:
+    """Read or create the keychain key. Opt-out and best-effort: any failure returns ``None``."""
+    if _keychain_disabled():
+        return None
+    try:
+        import keyring
+
+        service = _keychain_service()
+        try:
+            existing = keyring.get_password(service, KEYCHAIN_ACCOUNT)
+            if existing:
+                return _b64decode(existing)
+        except Exception:
+            pass  # no stored password yet
+        key = os.urandom(KEY_BYTES)
+        keyring.set_password(service, KEYCHAIN_ACCOUNT, base64.b64encode(key).decode("ascii"))
+        # Re-read after writing: if a concurrent process stored a different key in between,
+        # trust the persisted value so both processes converge on the same key.
+        try:
+            persisted = keyring.get_password(service, KEYCHAIN_ACCOUNT)
+            if persisted:
+                return _b64decode(persisted)
+        except Exception:
+            pass
+        return key
+    except Exception:
+        return None
+
+
+def resolve_config_dir() -> Path:
+    env_dir = os.environ.get("AGENTCORE_CONFIG_DIR")
+    return Path(env_dir) if env_dir is not None else Path.home() / ".agentcore"
+
+
+def keyfile_path() -> Path:
+    return resolve_config_dir() / "secrets.key"
+
+
+def _assert_keyfile_size(key: bytes, path: Path) -> bytes:
+    """A keyfile that exists but isn't KEY_BYTES long is corrupt; never overwrite it."""
+    if len(key) == KEY_BYTES:
+        return key
+    raise SecretEncryptionError(
+        f"Encryption key file at {path} is corrupt (expected {KEY_BYTES} bytes, found {len(key)}). "
+        "Move it aside and re-add your credentials, or restore the original key file"
+    )
+
+
+def _keyfile_key() -> bytes:
+    path = keyfile_path()
+    try:
+        if path.exists():
+            # A wrong-sized file is corruption, not a cue to mint a new key: overwriting it
+            # would orphan every secret sealed with the real key.
+            return _assert_keyfile_size(path.read_bytes(), path)
+        resolve_config_dir().mkdir(parents=True, exist_ok=True)
+        key = os.urandom(KEY_BYTES)
+        try:
+            # O_EXCL makes first-time creation race-safe: if another process created the file
+            # since the exists() check, read theirs instead of clobbering it.
+            fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_BINARY", 0), 0o600)
+        except FileExistsError:
+            return _assert_keyfile_size(path.read_bytes(), path)
+        with os.fdopen(fd, "wb") as fh:
+            fh.write(key)
+        return key
+    except SecretEncryptionError:
+        raise
+    except Exception as exc:
+        raise SecretEncryptionError(
+            f"Could not create or read the machine encryption key at {path}.", cause=exc
+        ) from exc
+
+
+def _read_keyfile_key_if_present() -> bytes | None:
+    try:
+        path = keyfile_path()
+        if path.exists():
+            key = path.read_bytes()
+            if len(key) == KEY_BYTES:
+                return key
+    except OSError:
+        pass
+    return None
+
+
+def _read_keychain_key_if_present() -> bytes | None:
+    if _keychain_disabled():
+        return None
+    try:
+        import keyring
+
+        existing = keyring.get_password(_keychain_service(), KEYCHAIN_ACCOUNT)
+        return _b64decode(existing) if existing else None
+    except Exception:
+        return None
+
+
+def resolve_encryption_key() -> bytes:
+    """The single key used to ENCRYPT new values: keychain first, keyfile fallback. Creates one if needed."""
+    global _cached_key
+    if _cached_key is not None:
+        return _cached_key
+    _cached_key = _try_keychain_key() or _keyfile_key()
+    return _cached_key
+
+
+def resolve_candidate_keys() -> list[bytes]:
+    """All keys usable for DECRYPTION (keychain, then keyfile). Read-only; may be empty."""
+    keys: list[bytes] = []
+    from_keychain = _read_keychain_key_if_present()
+    if from_keychain:
+        keys.append(from_keychain)
+    from_keyfile = _read_keyfile_key_if_present()
+    if from_keyfile and from_keyfile not in keys:
+        keys.append(from_keyfile)
+    return keys
+
+
+def reset_key_cache_for_tests() -> None:
+    global _cached_key
+    _cached_key = None

agentcore/lib/secrets/sensitive_keys.py

@@ -0,0 +1,55 @@
+"""Which env keys hold secrets that must be encrypted at rest (port of ``sensitive-keys.ts``)."""
+
+from __future__ import annotations
+
+import re
+from typing import Literal
+
+# Suffixes whose values are secrets.
+SECRET_SUFFIXES = (
+    "_API_KEY_SECRET",
+    "_WALLET_SECRET",
+    "_AUTHORIZATION_PRIVATE_KEY",
+    "_APP_SECRET",
+    "_CLIENT_SECRET",
+    "_API_KEY",
+)
+
+# Reference/identifier suffixes that are NOT secrets (stay readable).
+REFERENCE_SUFFIXES = ("_API_KEY_ID", "_APP_ID", "_CLIENT_ID", "_AUTHORIZATION_ID")
+
+SENSITIVE_KEY_PATTERNS: list[re.Pattern[str]] = [re.compile(f"{s}$") for s in SECRET_SUFFIXES]
+
+
+def _is_bare_model_credential(key: str) -> bool:
+    """Model-provider API keys are stored as bare ``AGENTCORE_CREDENTIAL_<NAME>`` (no secret suffix)."""
+    if not key.startswith("AGENTCORE_CREDENTIAL_"):
+        return False
+    return not key.endswith(REFERENCE_SUFFIXES)
+
+
+def is_sensitive_key(key: str) -> bool:
+    if key.endswith(REFERENCE_SUFFIXES):
+        return False
+    if any(p.search(key) for p in SENSITIVE_KEY_PATTERNS):
+        return True
+    return _is_bare_model_credential(key)
+
+
+def _normalize_credential_name_to_key(name: str) -> str:
+    return name.replace("-", "_").upper()
+
+
+def validate_credential_name_encryptable(name: str) -> Literal[True] | str:
+    """Reject credential names whose env var would end in a reference suffix (and so stay unencrypted).
+
+    Returns ``True`` if safe, else an error message (the ``True | str`` validator contract).
+    """
+    normalized = _normalize_credential_name_to_key(name)
+    collision = next((s for s in REFERENCE_SUFFIXES if normalized.endswith(s)), None)
+    if collision:
+        return (
+            f'Credential name "{name}" ends in a reserved reference suffix ({collision}) and its secret would not be '
+            "encrypted at rest. Choose a name that does not end in id/client-id/app-id/authorization-id."
+        )
+    return True

agentcore/lib/time_constants.py

@@ -0,0 +1,4 @@
+ONE_SECOND_MS = 1000
+ONE_MINUTE_MS = ONE_SECOND_MS * 60
+ONE_HOUR_MS = ONE_MINUTE_MS * 60
+ONE_DAY_MS = ONE_HOUR_MS * 24

agentcore/lib/utils/__init__.py

@@ -0,0 +1,47 @@
+from agentcore.lib.utils.aws_account import detect_aws_account
+from agentcore.lib.utils.credentials import SecureCredentials
+from agentcore.lib.utils.env import (
+    get_env_path,
+    get_env_var,
+    read_env_file,
+    remove_env_vars,
+    set_env_var,
+    write_env_file,
+)
+from agentcore.lib.utils.json_format import to_json_string
+from agentcore.lib.utils.json_rpc import parse_json_rpc_response
+from agentcore.lib.utils.platform import is_windows
+from agentcore.lib.utils.polling import PollResult, is_throttling_error, poll
+from agentcore.lib.utils.subprocess import (
+    SubprocessResult,
+    check_subprocess,
+    run_subprocess,
+    run_subprocess_capture,
+)
+from agentcore.lib.utils.time_parser import parse_time_string
+from agentcore.lib.utils.validation import resilient_parse, validate_agent_schema, validate_project_schema
+
+__all__ = [
+    "PollResult",
+    "SecureCredentials",
+    "SubprocessResult",
+    "check_subprocess",
+    "detect_aws_account",
+    "get_env_path",
+    "get_env_var",
+    "is_throttling_error",
+    "is_windows",
+    "parse_json_rpc_response",
+    "parse_time_string",
+    "poll",
+    "read_env_file",
+    "remove_env_vars",
+    "resilient_parse",
+    "run_subprocess",
+    "run_subprocess_capture",
+    "set_env_var",
+    "to_json_string",
+    "validate_agent_schema",
+    "validate_project_schema",
+    "write_env_file",
+]

agentcore/lib/utils/aws_account.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+import os
+
+
+def detect_aws_account() -> str | None:
+    """AWS account ID of the current credentials via STS GetCallerIdentity; ``None`` if unavailable."""
+    try:
+        import boto3
+
+        region = os.environ.get("AWS_REGION") or os.environ.get("AWS_DEFAULT_REGION") or "us-east-1"
+        response = boto3.session.Session().client("sts", region_name=region).get_caller_identity()
+        return response.get("Account") or None
+    except Exception:
+        return None

agentcore/lib/utils/credentials.py

@@ -0,0 +1,68 @@
+"""Redacting container for credential values (port of ``src/lib/utils/credentials.ts``)."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from types import MappingProxyType
+from typing import Any
+
+
+class SecureCredentials:
+    """Immutable credential store that never exposes values via ``str``/``repr``/JSON."""
+
+    __slots__ = ("_credentials",)
+
+    def __init__(self, credentials: Mapping[str, str] | None = None):
+        object.__setattr__(self, "_credentials", MappingProxyType(dict(credentials or {})))
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        raise AttributeError("SecureCredentials is immutable")
+
+    def get(self, key: str) -> str | None:
+        return self._credentials.get(key)
+
+    def has(self, key: str) -> bool:
+        return key in self._credentials
+
+    def __contains__(self, key: object) -> bool:
+        return key in self._credentials
+
+    @property
+    def size(self) -> int:
+        return len(self._credentials)
+
+    def __len__(self) -> int:
+        return len(self._credentials)
+
+    def is_empty(self) -> bool:
+        return not self._credentials
+
+    def keys(self) -> list[str]:
+        return list(self._credentials)
+
+    def merge(self, other: SecureCredentials | Mapping[str, str | None]) -> SecureCredentials:
+        """New instance with ``other`` overlaid on these credentials."""
+        merged = dict(self._credentials)
+        source = other._credentials if isinstance(other, SecureCredentials) else other
+        merged.update({k: v for k, v in source.items() if v is not None})
+        return SecureCredentials(merged)
+
+    def to_plain_object(self) -> dict[str, str]:
+        """WARNING: exposes credential values."""
+        return dict(self._credentials)
+
+    def to_json(self) -> dict[str, Any]:
+        return {"_redacted": "[CREDENTIALS REDACTED]", "count": len(self._credentials), "keys": self.keys()}
+
+    def __str__(self) -> str:
+        return f"[SecureCredentials: {len(self._credentials)} credential(s)]"
+
+    __repr__ = __str__
+
+    @staticmethod
+    def from_env_vars(env_vars: Mapping[str, str]) -> SecureCredentials:
+        return SecureCredentials(env_vars)
+
+    @staticmethod
+    def empty() -> SecureCredentials:
+        return SecureCredentials()

agentcore/lib/utils/dotenv.py

@@ -0,0 +1,32 @@
+"""Exact port of the ``parse`` function from the ``dotenv`` npm package (v17).
+
+``.env.local`` is shared with the TypeScript CLI, so parsing must match byte for byte, including
+its quirks: only ``\\n`` and ``\\r`` are unescaped in double-quoted values.
+"""
+
+from __future__ import annotations
+
+import re
+
+_LINE = re.compile(
+    r"(?:^|^)\s*(?:export\s+)?([A-Za-z0-9_.-]+)(?:\s*=\s*?|:\s+?)"
+    r"(\s*'(?:\\'|[^'])*'|\s*\"(?:\\\"|[^\"])*\"|\s*`(?:\\`|[^`])*`|[^#\r\n]+)?"
+    r"\s*(?:#.*)?(?:$|$)",
+    re.MULTILINE,
+)
+_SURROUNDING_QUOTES = re.compile(r"^(['\"`])([\s\S]*)\1$", re.MULTILINE)
+
+
+def parse(src: str | bytes) -> dict[str, str]:
+    text = src.decode("utf-8") if isinstance(src, bytes) else src
+    text = re.sub(r"\r\n?", "\n", text)
+    out: dict[str, str] = {}
+    for match in _LINE.finditer(text):
+        key = match.group(1)
+        value = (match.group(2) or "").strip()
+        maybe_quote = value[:1]
+        value = _SURROUNDING_QUOTES.sub(r"\2", value)
+        if maybe_quote == '"':
+            value = value.replace("\\n", "\n").replace("\\r", "\r")
+        out[key] = value
+    return out