agentcore-cli 0.31.1__py3-none-any.whl

agentcore/operations/fetch_access/types.py

@@ -0,0 +1,34 @@
+"""Port of src/cli/operations/fetch-access/types.ts (camelCase JSON-shaped records)."""
+
+from typing import Literal, NotRequired, TypedDict
+
+FetchResourceType = Literal["gateway", "agent", "harness"]
+
+
+class TokenFetchResult(TypedDict):
+    url: str
+    authType: str
+    token: NotRequired[str]
+    expiresIn: NotRequired[int]
+    message: NotRequired[str]
+
+
+class GatewayInfo(TypedDict):
+    name: str
+    authType: str
+
+
+class AgentInfo(TypedDict):
+    name: str
+    authType: str
+
+
+class HarnessInfo(TypedDict):
+    name: str
+    authType: str
+
+
+class ResourceInfo(TypedDict):
+    name: str
+    resourceType: FetchResourceType
+    authType: str

agentcore/operations/harness/__init__.py

@@ -0,0 +1 @@
+"""Harness operations (port of upstream ``src/cli/operations/harness``)."""

agentcore/operations/harness/orphan.py

@@ -0,0 +1,84 @@
+"""Preview-build ("orphan") harness detection (port of ``operations/harness/orphan.ts``).
+
+An orphan is a harness recorded in deployed-state.json that the old imperative preview build
+created: a real harness NOT part of any CloudFormation stack. The GA path stamps every CFN-managed
+record with ``provisioner: 'cloudformation'``, so a record without that marker can only be an
+orphan. Detection reads local state only — no AWS calls.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True)
+class OrphanHarness:
+    name: str
+    target_name: str
+    harness_id: str
+    harness_arn: str
+    region: str
+
+
+def _field(record: Any, camel: str, snake: str) -> Any:
+    if isinstance(record, Mapping):
+        return record.get(camel)
+    return getattr(record, snake, None)
+
+
+def is_orphan_harness_record(record: Any) -> bool:
+    return record is not None and _field(record, "provisioner", "provisioner") != "cloudformation"
+
+
+def region_from_harness_arn(harness_arn: str) -> str | None:
+    """Region segment of ``arn:aws:bedrock-agentcore:<region>:<account>:harness/<id>``."""
+    parts = harness_arn.split(":")
+    region = parts[3] if len(parts) > 3 else ""
+    return region or None
+
+
+def _targets(deployed_state: Any) -> Mapping[str, Any]:
+    if deployed_state is None:
+        return {}
+    if isinstance(deployed_state, Mapping):
+        return deployed_state.get("targets") or {}
+    return getattr(deployed_state, "targets", None) or {}
+
+
+def _harnesses(target: Any) -> Mapping[str, Any]:
+    resources = target.get("resources") if isinstance(target, Mapping) else getattr(target, "resources", None)
+    if resources is None:
+        return {}
+    if isinstance(resources, Mapping):
+        return resources.get("harnesses") or {}
+    return getattr(resources, "harnesses", None) or {}
+
+
+def find_orphan_harnesses(deployed_state: Any, harness_name: str | None = None) -> list[OrphanHarness]:
+    """Orphans across every target (optionally one name); records without a parseable region are skipped."""
+    orphans: list[OrphanHarness] = []
+    for target_name, target in _targets(deployed_state).items():
+        for name, record in _harnesses(target).items():
+            if harness_name and name != harness_name:
+                continue
+            if not is_orphan_harness_record(record):
+                continue
+            arn = _field(record, "harnessArn", "harness_arn") or ""
+            region = region_from_harness_arn(arn)
+            if not region:
+                continue
+            orphans.append(
+                OrphanHarness(
+                    name=name,
+                    target_name=target_name,
+                    harness_id=_field(record, "harnessId", "harness_id"),
+                    harness_arn=arn,
+                    region=region,
+                )
+            )
+    return orphans
+
+
+__all__ = ["OrphanHarness", "find_orphan_harnesses", "is_orphan_harness_record", "region_from_harness_arn"]

agentcore/operations/harness/skill_utils.py

@@ -0,0 +1,56 @@
+"""Harness skill helpers (port of ``operations/harness/skill-utils.ts``).
+
+Skills are handled in their camelCase JSON form (``{"s3Uri": ...}``, ``{"gitUrl": ..., "path": ...}``,
+``{"awsSkills": {"paths": [...]}}`` or ``{"path": ...}``).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from agentcore.lib.errors.types import ValidationError
+from agentcore.lib.result import Err, Ok
+from agentcore.lib.schemas.io.config_io import to_jsonable
+
+KEY_SEPARATOR = "::"
+
+
+def get_skill_key(skill: Any) -> str:
+    s = to_jsonable(skill)
+    if not isinstance(s, Mapping):
+        return f"path:{s}"
+    if "s3Uri" in s:
+        return f"s3:{s['s3Uri']}"
+    if "gitUrl" in s:
+        return f"git:{s['gitUrl']}{KEY_SEPARATOR + s['path'] if s.get('path') else ''}"
+    if "awsSkills" in s:
+        paths = (s.get("awsSkills") or {}).get("paths")
+        return f"awsSkills:{','.join(sorted(paths)) if paths is not None else '*'}"
+    return f"path:{s.get('path')}"
+
+
+def build_git_skill_key(git_url: str, git_path: str | None = None) -> str:
+    return f"git:{git_url}{KEY_SEPARATOR + git_path if git_path else ''}"
+
+
+def validate_git_skill_credential(project: Any, credential_name: str) -> Ok[None] | Err[Exception]:
+    spec = to_jsonable(project)
+    credential = next((c for c in spec.get("credentials") or [] if c.get("name") == credential_name), None)
+    if credential is None:
+        return Err(
+            ValidationError(
+                f"Credential '{credential_name}' not found in project. Run 'agentcore add credential' first."
+            )
+        )
+    if credential.get("authorizerType") != "ApiKeyCredentialProvider":
+        return Err(
+            ValidationError(
+                f"Credential '{credential_name}' is type '{credential.get('authorizerType')}'. Git skill auth "
+                "requires an ApiKeyCredentialProvider credential."
+            )
+        )
+    return Ok(None)
+
+
+__all__ = ["build_git_skill_key", "get_skill_key", "validate_git_skill_credential"]

agentcore/operations/identity/__init__.py

@@ -0,0 +1,33 @@
+"""AgentCore Identity credential-provider operations (port of src/cli/operations/identity)."""
+
+from agentcore.operations.identity.api_key_credential_provider import (
+    api_key_provider_exists,
+    create_api_key_provider,
+    set_token_vault_kms_key,
+    update_api_key_provider,
+)
+from agentcore.operations.identity.oauth2_credential_provider import (
+    OAuth2ProviderParams,
+    OAuth2ProviderResult,
+    create_oauth2_provider,
+    get_oauth2_provider,
+    o_auth2_provider_exists,
+    oauth2_provider_exists,
+    update_oauth2_provider,
+)
+from agentcore.primitives.credential_utils import compute_default_credential_env_var_name
+
+__all__ = [
+    "OAuth2ProviderParams",
+    "OAuth2ProviderResult",
+    "api_key_provider_exists",
+    "compute_default_credential_env_var_name",
+    "create_api_key_provider",
+    "create_oauth2_provider",
+    "get_oauth2_provider",
+    "o_auth2_provider_exists",
+    "oauth2_provider_exists",
+    "set_token_vault_kms_key",
+    "update_api_key_provider",
+    "update_oauth2_provider",
+]

agentcore/operations/identity/api_key_credential_provider.py

@@ -0,0 +1,68 @@
+"""Imperative AWS SDK operations for API key credential providers
+(port of src/cli/operations/identity/api-key-credential-provider.ts).
+
+AgentCore Identity resources are not modeled as CDK constructs; these run as a pre-deploy step.
+``client`` is a boto3 ``bedrock-agentcore-control`` client.
+"""
+
+from typing import Any
+
+from agentcore.aws._aws_errors import aws_error_name
+from agentcore.lib.errors.types import to_error
+from agentcore.lib.result import Err, Ok
+
+_CONFLICT_CODES = ("ConflictException", "ResourceAlreadyExistsException")
+
+
+def _arn(response: dict[str, Any]) -> dict[str, Any]:
+    arn = response.get("credentialProviderArn")
+    return {"credentialProviderArn": arn} if arn is not None else {}
+
+
+def api_key_provider_exists(client: Any, provider_name: str) -> bool:
+    """True if the provider exists; False on ResourceNotFoundException; other errors propagate."""
+    try:
+        client.get_api_key_credential_provider(name=provider_name)
+        return True
+    except Exception as exc:
+        if aws_error_name(exc) == "ResourceNotFoundException":
+            return False
+        raise
+
+
+def create_api_key_provider(client: Any, provider_name: str, api_key: str) -> Ok[dict[str, Any]] | Err[Exception]:
+    """Create an API key credential provider. Idempotent: an existing provider counts as success."""
+    try:
+        client.create_api_key_credential_provider(name=provider_name, apiKey=api_key)
+        # The create response doesn't include credentialProviderArn — fetch it.
+        return Ok(_arn(client.get_api_key_credential_provider(name=provider_name)))
+    except Exception as exc:  # noqa: BLE001
+        if aws_error_name(exc) in _CONFLICT_CODES:
+            try:
+                return Ok(_arn(client.get_api_key_credential_provider(name=provider_name)))
+            except Exception:  # noqa: BLE001
+                return Ok({})
+        return Err(to_error(exc))
+
+
+def update_api_key_provider(client: Any, provider_name: str, api_key: str) -> Ok[dict[str, Any]] | Err[Exception]:
+    """Update an existing API key credential provider with a new API key."""
+    try:
+        client.update_api_key_credential_provider(name=provider_name, apiKey=api_key)
+        return Ok(_arn(client.get_api_key_credential_provider(name=provider_name)))
+    except Exception as exc:  # noqa: BLE001
+        return Err(to_error(exc))
+
+
+def set_token_vault_kms_key(
+    client: Any, kms_key_arn: str, token_vault_id: str | None = None
+) -> Ok[None] | Err[Exception]:
+    """Configure customer-managed KMS encryption for the token vault."""
+    params: dict[str, Any] = {"kmsConfiguration": {"keyType": "CustomerManagedKey", "kmsKeyArn": kms_key_arn}}
+    if token_vault_id is not None:
+        params["tokenVaultId"] = token_vault_id
+    try:
+        client.set_token_vault_cmk(**params)
+        return Ok(None)
+    except Exception as exc:  # noqa: BLE001
+        return Err(to_error(exc))

agentcore/operations/identity/oauth2_credential_provider.py

@@ -0,0 +1,95 @@
+"""Imperative AWS SDK operations for OAuth2 credential providers
+(port of src/cli/operations/identity/oauth2-credential-provider.ts).
+
+``client`` is a boto3 ``bedrock-agentcore-control`` client.
+"""
+
+from dataclasses import dataclass
+from typing import Any
+
+from agentcore.aws._aws_errors import aws_error_name
+from agentcore.lib.errors.types import ServiceError, to_error
+from agentcore.lib.result import Err, Ok
+
+OAuth2ProviderResult = Ok[dict[str, Any]] | Err[Exception]
+
+
+@dataclass
+class OAuth2ProviderParams:
+    name: str
+    vendor: str
+    discovery_url: str
+    client_id: str
+    client_secret: str
+
+
+def _extract_result(response: dict[str, Any]) -> OAuth2ProviderResult:
+    """Create/Get/Update responses share the same shape."""
+    arn = response.get("credentialProviderArn")
+    if not arn:
+        return Err(ServiceError("missing credentialProviderArn in response"))
+    value: dict[str, Any] = {"credentialProviderArn": arn}
+    secret_arn = (response.get("clientSecretArn") or {}).get("secretArn")
+    if secret_arn is not None:
+        value["clientSecretArn"] = secret_arn
+    if response.get("callbackUrl") is not None:
+        value["callbackUrl"] = response["callbackUrl"]
+    return Ok(value)
+
+
+def o_auth2_provider_exists(client: Any, provider_name: str) -> bool:
+    try:
+        client.get_oauth2_credential_provider(name=provider_name)
+        return True
+    except Exception as exc:
+        if aws_error_name(exc) == "ResourceNotFoundException":
+            return False
+        raise
+
+
+oauth2_provider_exists = o_auth2_provider_exists
+
+
+def _build_oauth2_config(params: OAuth2ProviderParams) -> dict[str, Any]:
+    """Always customOauth2ProviderConfig; the vendor field controls server-side behaviour."""
+    return {
+        "name": params.name,
+        "credentialProviderVendor": params.vendor,
+        "oauth2ProviderConfigInput": {
+            "customOauth2ProviderConfig": {
+                "clientId": params.client_id,
+                "clientSecret": params.client_secret,
+                "oauthDiscovery": {"discoveryUrl": params.discovery_url},
+            }
+        },
+    }
+
+
+def create_oauth2_provider(client: Any, params: OAuth2ProviderParams) -> OAuth2ProviderResult:
+    """Create an OAuth2 provider; on conflict (created concurrently) fall back to update."""
+    try:
+        result = _extract_result(client.create_oauth2_credential_provider(**_build_oauth2_config(params)))
+        if not result.success:
+            result = get_oauth2_provider(client, params.name)
+        return result
+    except Exception as exc:  # noqa: BLE001
+        if aws_error_name(exc) in ("ConflictException", "ResourceAlreadyExistsException"):
+            return update_oauth2_provider(client, params)
+        return Err(to_error(exc))
+
+
+def get_oauth2_provider(client: Any, name: str) -> OAuth2ProviderResult:
+    try:
+        return _extract_result(client.get_oauth2_credential_provider(name=name))
+    except Exception as exc:  # noqa: BLE001
+        return Err(to_error(exc))
+
+
+def update_oauth2_provider(client: Any, params: OAuth2ProviderParams) -> OAuth2ProviderResult:
+    try:
+        result = _extract_result(client.update_oauth2_credential_provider(**_build_oauth2_config(params)))
+        if not result.success:
+            result = get_oauth2_provider(client, params.name)
+        return result
+    except Exception as exc:  # noqa: BLE001
+        return Err(to_error(exc))

agentcore/operations/ingest/__init__.py

@@ -0,0 +1,184 @@
+"""Start KB ingestion jobs for a deployed knowledge base (port of operations/ingest/index.ts)."""
+
+from __future__ import annotations
+
+import re
+import threading
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+from agentcore.aws import bedrock_agent
+from agentcore.aws._aws_errors import aws_error_name, get_error_message
+from agentcore.lib.errors.types import IngestionError
+from agentcore.lib.result import Err, Ok
+
+
+@dataclass(frozen=True)
+class ConcurrentRetryPolicy:
+    max_attempts: int
+    """Max attempts per data source (1 = no retry)."""
+    delay_ms: int
+    """Delay before each retry, in milliseconds."""
+
+
+# Bedrock allows only one in-flight ingestion job per KB; a second StartIngestionJob for a multi-DS
+# KB usually races and gets a ConflictException. Retry up to 4 times (~5min at 75s intervals).
+DEFAULT_CONCURRENT_RETRY_POLICY = ConcurrentRetryPolicy(max_attempts=5, delay_ms=75_000)
+
+
+@dataclass
+class StartedIngestion:
+    data_source_id: str
+    uri: str
+    ingestion_job_id: str
+
+    def to_json(self) -> dict[str, str]:
+        return {"dataSourceId": self.data_source_id, "uri": self.uri, "ingestionJobId": self.ingestion_job_id}
+
+
+@dataclass
+class RunKbIngestionInput:
+    knowledge_base_name: str
+    deployed_state: Any
+    """``DeployedState`` model or camelCase dict."""
+    target_name: str
+    region: str
+    data_source_uri: str | None = None
+    """When set, ingest only the data source whose recorded URI matches."""
+    concurrent_retry_policy: ConcurrentRetryPolicy | None = None
+    on_progress: Callable[[str], None] | None = None
+    signal: threading.Event | None = None
+    """Abort signal: when set, cancels pending retry sleeps and fails the in-flight data source."""
+
+
+@dataclass
+class RunKbIngestionSuccess:
+    started_jobs: list[StartedIngestion] = field(default_factory=list)
+
+
+_CONCURRENT_RE = re.compile(r"concurrent ingestion jobs", re.IGNORECASE)
+
+
+def _is_concurrent_limit_error(err: BaseException) -> bool:
+    if aws_error_name(err) == "ConflictException":
+        return True
+    return bool(_CONCURRENT_RE.search(get_error_message(err)))
+
+
+def _sleep(ms: int, signal: threading.Event | None) -> None:
+    """Sleep that returns early when the abort signal fires."""
+    if signal is None:
+        threading.Event().wait(ms / 1000)
+    elif not signal.is_set():
+        signal.wait(ms / 1000)
+
+
+def _get(obj: Any, snake: str, camel: str) -> Any:
+    if obj is None:
+        return None
+    return obj.get(camel) if isinstance(obj, Mapping) else getattr(obj, snake, None)
+
+
+def _find_deployed_kb(state: Any, target_name: str, kb_name: str) -> Any:
+    target = (_get(state, "targets", "targets") or {}).get(target_name)
+    resources = _get(target, "resources", "resources")
+    return (_get(resources, "knowledge_bases", "knowledgeBases") or {}).get(kb_name)
+
+
+def run_kb_ingestion_by_name(
+    input: RunKbIngestionInput,
+) -> Ok[RunKbIngestionSuccess] | Err[IngestionError]:
+    """Start ingestion for every data source on a deployed KB (sequentially, retrying on conflicts).
+
+    Pre-flight failures (KB not deployed, no data sources, unknown URI) are user errors. If any data
+    source fails to start, returns a failure listing them; successful starts are not rolled back.
+    """
+    retry_policy = input.concurrent_retry_policy or DEFAULT_CONCURRENT_RETRY_POLICY
+    name, target_name, signal = input.knowledge_base_name, input.target_name, input.signal
+
+    deployed = _find_deployed_kb(input.deployed_state, target_name, name)
+    if not deployed:
+        return Err(
+            IngestionError(
+                f"Knowledge base '{name}' has not been deployed to target '{target_name}'. Run 'agentcore deploy' first.",
+                error_source="user",
+            )
+        )
+
+    data_sources = [
+        (_get(ds, "data_source_id", "dataSourceId"), _get(ds, "uri", "uri"))
+        for ds in _get(deployed, "data_sources", "dataSources") or []
+    ]
+    if not data_sources:
+        return Err(IngestionError(f"Knowledge base '{name}' has no data sources to ingest.", error_source="user"))
+
+    to_ingest = data_sources
+    if input.data_source_uri:
+        to_ingest = [ds for ds in data_sources if ds[1] == input.data_source_uri]
+        if not to_ingest:
+            return Err(
+                IngestionError(
+                    f"Data source '{input.data_source_uri}' not found on knowledge base '{name}'.",
+                    error_source="user",
+                )
+            )
+
+    kb_id = _get(deployed, "knowledge_base_id", "knowledgeBaseId")
+    started_jobs: list[StartedIngestion] = []
+    failures: list[tuple[str, str, Any]] = []
+    for ds_id, uri in to_ingest:
+        if signal is not None and signal.is_set():
+            failures.append((ds_id, uri, Exception("Aborted before start")))
+            continue
+        last_error: Any = None
+        started = False
+        for attempt in range(1, retry_policy.max_attempts + 1):
+            try:
+                job = bedrock_agent.start_ingestion_job(
+                    region=input.region, knowledge_base_id=kb_id, data_source_id=ds_id
+                )
+                job_id = job.get("ingestionJobId") if isinstance(job, Mapping) else None
+                if not job_id:
+                    last_error = Exception("No ingestionJobId in StartIngestionJob response")
+                    break
+                started_jobs.append(StartedIngestion(ds_id, uri, job_id))
+                started = True
+                break
+            except Exception as exc:  # noqa: BLE001 - every service error is reported per data source
+                last_error = exc
+                if not _is_concurrent_limit_error(exc) or attempt == retry_policy.max_attempts:
+                    break
+                delay_seconds = round(retry_policy.delay_ms / 1000)
+                if input.on_progress:
+                    input.on_progress(
+                        f"{ds_id} ({uri}): another ingestion job is running on this KB, retry "
+                        f"{attempt}/{retry_policy.max_attempts - 1} in {delay_seconds}s…"
+                    )
+                _sleep(retry_policy.delay_ms, signal)
+                if signal is not None and signal.is_set():
+                    last_error = Exception("Aborted while waiting for concurrent ingestion job to drain")
+                    break
+        if not started:
+            failures.append((ds_id, uri, last_error))
+
+    if failures:
+        detail = "\n".join(
+            f"  {ds_id} ({uri}): {get_error_message(e) if isinstance(e, BaseException) else str(e)}"
+            for ds_id, uri, e in failures
+        )
+        return Err(
+            IngestionError(f"Failed to start ingestion for {len(failures)} of {len(to_ingest)} data sources:\n{detail}")
+        )
+
+    return Ok(RunKbIngestionSuccess(started_jobs=started_jobs))
+
+
+__all__ = [
+    "DEFAULT_CONCURRENT_RETRY_POLICY",
+    "ConcurrentRetryPolicy",
+    "RunKbIngestionInput",
+    "RunKbIngestionSuccess",
+    "StartedIngestion",
+    "run_kb_ingestion_by_name",
+]

agentcore/operations/init/__init__.py

@@ -0,0 +1,3 @@
+from agentcore.operations.init.files import InitGitRepoResult, init_git_repo, write_env_file, write_gitignore
+
+__all__ = ["InitGitRepoResult", "init_git_repo", "write_env_file", "write_gitignore"]

agentcore/operations/init/files.py

@@ -0,0 +1,59 @@
+"""Project init helpers (port of src/cli/operations/init/files.ts)."""
+
+import os
+from dataclasses import dataclass
+from typing import Literal
+
+from agentcore.lib import run_subprocess_capture
+
+AGENTCORE_GITIGNORE = """# Secrets (local environment files are never committed)
+.env.local
+
+# CDK Build Artifacts
+cdk/cdk.out/
+cdk/node_modules/
+
+# CLI Internals
+.cli/*
+
+# Ephemeral Staging
+.cache/*
+
+# Exception: Commit the State
+!.cli/deployed-state.json
+"""
+
+
+def write_gitignore(config_base_dir: str) -> None:
+    with open(os.path.join(config_base_dir, ".gitignore"), "w", encoding="utf-8", newline="") as fh:
+        fh.write(AGENTCORE_GITIGNORE)
+
+
+def write_env_file(config_base_dir: str) -> None:
+    """Write an empty .env.local file for storing secrets."""
+    with open(os.path.join(config_base_dir, ".env.local"), "w", encoding="utf-8") as fh:
+        fh.write("")
+
+
+@dataclass
+class InitGitRepoResult:
+    status: Literal["success", "skipped", "error"]
+    message: str | None = None
+
+
+def init_git_repo(project_root: str) -> InitGitRepoResult:
+    """Initialize a git repository at the project root; skipped if git is missing or already in a repo."""
+    if run_subprocess_capture("git", ["--version"], cwd=project_root).code != 0:
+        return InitGitRepoResult("skipped", "git not available")
+    if run_subprocess_capture("git", ["rev-parse", "--is-inside-work-tree"], cwd=project_root).code == 0:
+        return InitGitRepoResult("skipped", "already in a git repository")
+    result = run_subprocess_capture("git", ["init"], cwd=project_root)
+    if result.code != 0:
+        return InitGitRepoResult("error", result.stderr or "git init failed")
+    result = run_subprocess_capture("git", ["add", "."], cwd=project_root)
+    if result.code != 0:
+        return InitGitRepoResult("error", result.stderr or "git add failed")
+    result = run_subprocess_capture("git", ["commit", "-m", "Initial commit"], cwd=project_root)
+    if result.code != 0:
+        return InitGitRepoResult("error", result.stderr or "git commit failed")
+    return InitGitRepoResult("success")

agentcore/operations/insights/__init__.py

@@ -0,0 +1,21 @@
+"""Legacy insights operations (port of operations/insights/index.ts)."""
+
+from agentcore.operations.insights.insights_storage import (
+    INSIGHTS_DIR,
+    delete_local_insights_run,
+    list_insights_runs,
+    load_insights_run,
+    save_insights_run,
+    update_insights_run,
+)
+from agentcore.operations.insights.run_insights import run_insights_command
+
+__all__ = [
+    "INSIGHTS_DIR",
+    "delete_local_insights_run",
+    "list_insights_runs",
+    "load_insights_run",
+    "run_insights_command",
+    "save_insights_run",
+    "update_insights_run",
+]