agentcore-cli 0.31.1__py3-none-any.whl

agentcore/cli/commands/status/command.py

@@ -0,0 +1,321 @@
+"""`agentcore status` registration and rendering (port of ``commands/status/command.tsx``)."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from datetime import datetime
+from typing import Any
+
+import typer
+
+from agentcore.aws import agentcore_datasets
+from agentcore.cli.commands.status._guards import require_project
+from agentcore.cli.commands.status.action import (
+    ResourceStatusEntry,
+    handle_project_status,
+    handle_runtime_lookup,
+    load_status_config,
+)
+from agentcore.cli.commands.status.constants import DEPLOYMENT_STATE_COLORS, DEPLOYMENT_STATE_LABELS
+from agentcore.cli.constants import ANSI, COMMAND_DESCRIPTIONS
+from agentcore.cli.errors import get_error_message
+
+VALID_RESOURCE_TYPES = (
+    "agent",
+    "runtime-endpoint",
+    "memory",
+    "credential",
+    "gateway",
+    "evaluator",
+    "online-eval",
+    "payment",
+    "policy-engine",
+    "policy",
+    "config-bundle",
+    "dataset",
+    "knowledge-base",
+    "harness",
+    "capacity-provider",
+)
+VALID_STATES = ("deployed", "local-only", "pending-removal")
+
+_COLOR = {"green": ANSI.green, "yellow": ANSI.yellow, "red": ANSI.red, "cyan": ANSI.cyan}
+_BOLD = "\x1b[1m" if ANSI.reset else ""
+
+
+def _c(text: str, color: str | None) -> str:
+    code = _COLOR.get(color or "", "")
+    return f"{code}{text}{ANSI.reset}" if code else text
+
+
+def _dim(text: str) -> str:
+    return f"{ANSI.dim}{text}{ANSI.reset}" if ANSI.dim else text
+
+
+def _bold(text: str) -> str:
+    return f"{_BOLD}{text}{ANSI.reset}" if _BOLD else text
+
+
+def filter_resources(
+    resources: list[ResourceStatusEntry],
+    *,
+    type_: str | None = None,
+    state: str | None = None,
+    runtime: str | None = None,
+    name: str | None = None,
+) -> list[ResourceStatusEntry]:
+    out = resources
+    if type_:
+        out = [r for r in out if r["resourceType"] == type_]
+    if state:
+        out = [r for r in out if r["deploymentState"] == state]
+    if runtime:
+        out = [r for r in out if r["resourceType"] != "agent" or r["name"] == runtime]
+    # --name drills into one resource (meant for knowledge-base); a bare --name narrows across types.
+    if name:
+        out = [r for r in out if r["name"] == name]
+    return out
+
+
+def _state_label(state: str) -> str:
+    return _c(DEPLOYMENT_STATE_LABELS.get(state, state), DEPLOYMENT_STATE_COLORS.get(state))
+
+
+def format_resource_entry(entry: Mapping[str, Any], show_runtime: bool = False) -> str:
+    line = f"  {entry['name']}: {_state_label(entry['deploymentState'])}"
+    if entry.get("detail"):
+        line += f" - Runtime: {entry['detail']}" if show_runtime else _dim(f" ({entry['detail']})")
+    if entry.get("identifier"):
+        line += _dim(f" ({entry['identifier']})")
+    if entry.get("error"):
+        line += _c(f" - Error: {entry['error']}", "red")
+    return line
+
+
+def _short_date(epoch_seconds: float) -> str:
+    """``toLocaleDateString([], {month: 'short', day: 'numeric', year: 'numeric'})`` in en-US form."""
+    dt = datetime.fromtimestamp(epoch_seconds)
+    return f"{dt.strftime('%b')} {dt.day}, {dt.year}"
+
+
+def get_dataset_status(*, region: str, dataset_id: str, name: str) -> dict[str, Any]:
+    """DRAFT info plus version history (port of ``operations/dataset/status.ts``)."""
+    info = agentcore_datasets.get_dataset(region=region, dataset_id=dataset_id)
+    versions = agentcore_datasets.list_dataset_versions(region=region, dataset_id=dataset_id)
+    return {
+        "name": name,
+        "datasetId": dataset_id,
+        "schemaType": info.get("schemaType"),
+        "status": info.get("status"),
+        "draftExampleCount": info.get("exampleCount"),
+        "draftStatus": info.get("draftStatus") or "UNKNOWN",
+        "updatedAt": info.get("updatedAt"),
+        "versions": versions.get("versions") or [],
+    }
+
+
+def _section(lines: list[str], title: str) -> None:
+    lines.append("")
+    lines.append(_bold(title))
+
+
+def render_status(result: Any, filtered: list[ResourceStatusEntry], dataset_details: list[dict[str, Any]]) -> str:
+    """Plain-text rendering of upstream's Ink status view."""
+    by_type: dict[str, list[ResourceStatusEntry]] = {}
+    for entry in filtered:
+        by_type.setdefault(entry["resourceType"], []).append(entry)
+
+    def of(kind: str) -> list[ResourceStatusEntry]:
+        return by_type.get(kind, [])
+
+    region = f", {result.target_region}" if result.target_region else ""
+    target = result.target_name if result.target_name is not None else "No target configured"
+    lines = [_bold(f"AgentCore Status (target: {target}{region})")]
+
+    agents, endpoints = of("agent"), of("runtime-endpoint")
+
+    def endpoint_line(ep: Mapping[str, Any], label: str, indent: str) -> str:
+        detail = _dim(ep.get("detail") or "")
+        state = _c(
+            f"[{DEPLOYMENT_STATE_LABELS.get(ep['deploymentState'], ep['deploymentState'])}]",
+            DEPLOYMENT_STATE_COLORS.get(ep["deploymentState"]),
+        )
+        return f"{indent}◉ {label} {detail} {state}"
+
+    if agents:
+        _section(lines, "Agents")
+        for entry in agents:
+            lines.append(format_resource_entry(entry, show_runtime=True))
+            if entry.get("invocationUrl"):
+                lines.append(_dim(f"  URL: {entry['invocationUrl']}"))
+            for ep in (e for e in endpoints if e.get("parentName") == entry["name"]):
+                lines.append(endpoint_line(ep, ep["name"], "    "))
+    elif endpoints:
+        _section(lines, "Runtime Endpoints")
+        for ep in endpoints:
+            lines.append(endpoint_line(ep, f"{ep.get('parentName')}/{ep['name']}", "  "))
+
+    for kind, title in (
+        ("memory", "Memories"),
+        ("credential", "Credentials"),
+        ("gateway", "Gateways"),
+        ("evaluator", "Evaluators"),
+        ("online-eval", "Online Eval Configs"),
+        ("policy-engine", "Policy Engines"),
+        ("policy", "Policies"),
+        ("config-bundle", "Config Bundles"),
+    ):
+        if of(kind):
+            _section(lines, title)
+            lines.extend(format_resource_entry(e) for e in of(kind))
+
+    if of("dataset"):
+        _section(lines, "Datasets")
+        lines.extend(format_resource_entry(e) for e in of("dataset"))
+        for d in dataset_details:
+            lines.append("")
+            lines.append("  " + _bold(str(d["name"])))
+            lines.append(_dim(f"   Schema: {d['schemaType']}"))
+            draft = _c(f"({d['draftStatus']})", "yellow" if d["draftStatus"] == "MODIFIED" else "green")
+            lines.append(
+                f"   DRAFT: {d['draftExampleCount']} examples {draft} · Updated: {_short_date(d['updatedAt'])}"
+            )
+            if d["versions"]:
+                lines.append(_dim("   Versions:"))
+                for i, v in enumerate(d["versions"]):
+                    body = (
+                        _c(f"FAILED: {v['failureReason']}", "red")
+                        if v.get("failureReason")
+                        else f"{v.get('exampleCount')} examples"
+                    )
+                    text = (
+                        f"     v{v['datasetVersion']}{' (latest)' if i == 0 else ''} — {body}"
+                        f" · Created: {_short_date(v['createdAt'])}"
+                    )
+                    lines.append(_dim(text) if i > 0 else text)
+            else:
+                lines.append(_dim("   No published versions"))
+
+    if of("knowledge-base"):
+        _section(lines, "Knowledge Bases")
+        lines.extend(format_resource_entry(e) for e in of("knowledge-base"))
+
+    if of("payment"):
+        _section(lines, "Payments")
+        for entry in of("payment"):
+            lines.append(format_resource_entry(entry))
+            for connector in entry.get("paymentConnectors") or []:
+                lines.append(f"    {connector['name']}: {connector['status']} ({connector['connectorId']})")
+                if connector.get("authorizationUrl"):
+                    lines.append(f"    Authorization: {_c(connector['authorizationUrl'], 'cyan')}")
+                if connector.get("credentialProviderArn"):
+                    lines.append(_dim(f"    Credential provider: {connector['credentialProviderArn']}"))
+                if connector.get("error"):
+                    lines.append(_c(f"    {connector['error']}", "red"))
+
+    if of("harness"):
+        _section(lines, "Harnesses")
+        lines.extend(format_resource_entry(e) for e in of("harness"))
+
+    if not filtered:
+        lines.append(_dim("No resources match the given filters."))
+    return "\n".join(lines)
+
+
+def _print_json(payload: Any) -> None:
+    typer.echo(json.dumps(payload, indent=2, ensure_ascii=False))
+
+
+def status_command(
+    runtime_id: str | None = typer.Option(None, "--runtime-id", help="Look up a specific runtime by ID"),
+    target: str | None = typer.Option(None, "--target", help="Select deployment target"),
+    type_: str | None = typer.Option(
+        None, "--type", help=f"Filter by resource type ({', '.join(VALID_RESOURCE_TYPES)})"
+    ),
+    state: str | None = typer.Option(
+        None, "--state", help="Filter by deployment state (deployed, local-only, pending-removal)"
+    ),
+    runtime: str | None = typer.Option(None, "--runtime", help="Filter to a specific runtime"),
+    name: str | None = typer.Option(None, "--name", help="Show details for a single resource by name (knowledge-base)"),
+    as_json: bool = typer.Option(False, "--json", help="Output as JSON"),
+) -> None:
+    require_project()
+
+    if type_ and type_ not in VALID_RESOURCE_TYPES:
+        typer.echo(_c(f"Invalid resource type '{type_}'. Valid types: {', '.join(VALID_RESOURCE_TYPES)}", "red"))
+        raise typer.Exit(1)
+    if state and state not in VALID_STATES:
+        typer.echo(_c(f"Invalid state '{state}'. Valid states: {', '.join(VALID_STATES)}", "red"))
+        raise typer.Exit(1)
+
+    try:
+        if runtime_id:
+            lookup = handle_runtime_lookup(load_status_config(), agent_runtime_id=runtime_id, target_name=target)
+            if not lookup.success:
+                if as_json:
+                    _print_json(lookup.to_json())
+                else:
+                    typer.echo(_c(str(lookup.error), "red"))
+                raise typer.Exit(1)
+            if as_json:
+                _print_json(lookup.to_json())
+                return
+            status_text = f" - Runtime status: {lookup.runtime_status}" if lookup.runtime_status else ""
+            typer.echo(f"AgentCore Status - {lookup.runtime_id} (target: {lookup.target_name}){status_text}")
+            return
+
+        kb_name = name if name and (not type_ or type_ == "knowledge-base") else None
+        result = handle_project_status(load_status_config(), target_name=target, knowledge_base_name=kb_name)
+        if not result.success:
+            if as_json:
+                _print_json(result.to_json())
+            else:
+                typer.echo(_c(str(result.error), "red"))
+            raise typer.Exit(1)
+
+        filtered = filter_resources(result.resources, type_=type_, state=state, runtime=runtime, name=name)
+        if as_json:
+            _print_json(result.to_json(filtered))
+            return
+
+        dataset_details: list[dict[str, Any]] = []
+        datasets = [r for r in filtered if r["resourceType"] == "dataset"]
+        if type_ == "dataset" and datasets and result.target_region and result.target_name:
+            deployed = (
+                ((result.deployed_state.get("targets") or {}).get(result.target_name) or {}).get("resources") or {}
+            ).get("datasets") or {}
+            for d in datasets:
+                if d["deploymentState"] == "deployed" and deployed.get(d["name"]):
+                    try:
+                        dataset_details.append(
+                            get_dataset_status(
+                                region=result.target_region, dataset_id=deployed[d["name"]]["datasetId"], name=d["name"]
+                            )
+                        )
+                    except Exception:  # noqa: BLE001
+                        pass
+
+        typer.echo(render_status(result, filtered, dataset_details))
+    except typer.Exit:
+        raise
+    except Exception as exc:  # noqa: BLE001
+        typer.echo(_c(f"Error: {get_error_message(exc)}", "red"))
+        raise typer.Exit(1) from None
+
+
+def register_status(app: typer.Typer) -> None:
+    description = COMMAND_DESCRIPTIONS["status"]
+    app.command("status", help=description)(status_command)
+    app.command("s", help=description, hidden=True)(status_command)
+
+
+__all__ = [
+    "VALID_RESOURCE_TYPES",
+    "VALID_STATES",
+    "filter_resources",
+    "format_resource_entry",
+    "get_dataset_status",
+    "register_status",
+    "render_status",
+]

agentcore/cli/commands/status/constants.py

@@ -0,0 +1,36 @@
+"""Status display constants (port of ``commands/status/constants.ts``)."""
+
+from __future__ import annotations
+
+from typing import Literal
+from urllib.parse import quote
+
+from agentcore.aws.partition import service_endpoint
+
+ResourceDeploymentState = Literal["deployed", "local-only", "pending-removal"]
+
+# STATUS_COLORS from tui/theme.ts: success green, warning yellow, error red.
+DEPLOYMENT_STATE_COLORS: dict[str, str] = {"deployed": "green", "local-only": "yellow", "pending-removal": "red"}
+
+DEPLOYMENT_STATE_LABELS: dict[str, str] = {
+    "deployed": "Deployed",
+    "local-only": "Local only",
+    "pending-removal": "Removed locally",
+}
+
+
+def encode_uri_component(value: str) -> str:
+    return quote(value, safe="-_.!~*'()")
+
+
+def build_runtime_invocation_url(region: str, runtime_arn: str) -> str:
+    return f"https://{service_endpoint('bedrock-agentcore', region)}/runtimes/{encode_uri_component(runtime_arn)}/invocations"
+
+
+__all__ = [
+    "DEPLOYMENT_STATE_COLORS",
+    "DEPLOYMENT_STATE_LABELS",
+    "ResourceDeploymentState",
+    "build_runtime_invocation_url",
+    "encode_uri_component",
+]

agentcore/cli/commands/status/format_knowledge_base.py

@@ -0,0 +1,111 @@
+"""Knowledge base status rendering (port of ``commands/status/format-knowledge-base.ts``)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class KbIngestionDetail:
+    status: str | None = None
+    started_at: str | None = None
+    updated_at: str | None = None
+    completed_at: str | None = None
+    scanned: int | None = None
+    indexed: int | None = None
+    modified: int | None = None
+    failed: int | None = None
+    deleted: int | None = None
+
+
+@dataclass
+class KbDataSourceDetail:
+    uri: str
+    data_source_id: str
+    ingestion: KbIngestionDetail | None = None
+
+
+@dataclass
+class KbStatusDetail:
+    name: str
+    knowledge_base_id: str
+    status: str | None = None
+    gateway_names: list[str] = field(default_factory=list)
+    data_sources: list[KbDataSourceDetail] = field(default_factory=list)
+
+
+FAILURE_HINTS = [
+    "Next steps:",
+    "  → Retry ingestion:  agentcore run ingest --name <kb>",
+    "  → Common causes:",
+    "    • Document format not supported (.txt, .md, .html, .pdf, .doc, .csv, .xls)",
+    "    • File exceeds 50MB size limit",
+    "    • S3 bucket permissions — ensure the KB role has s3:GetObject access",
+    "    • Data source credentials expired (Confluence, SharePoint, etc.)",
+]
+
+
+def format_knowledge_base_detail(kb: KbStatusDetail) -> list[str]:
+    """The multi-line KB status block (``status --type knowledge-base --name X``)."""
+    lines = [f"Knowledge Base: {kb.name}"]
+    mark = "✓" if kb.status == "ACTIVE" else "⟳"
+    lines.append(f"  Knowledge Base:  {mark} {kb.status or 'UNKNOWN'} ({kb.knowledge_base_id})")
+    any_failed = False
+    lines.append(f"  Data Sources ({len(kb.data_sources)}):")
+    for ds in kb.data_sources:
+        ing = ds.ingestion
+        status = ing.status if ing else None
+        ds_mark = "✗" if status == "FAILED" else "✓" if status in ("COMPLETE", "SUCCEEDED") else "⟳"
+        lines.append(f"    {ds_mark} {ds.uri} ({ds.data_source_id})")
+        if ing:
+            if ing.status == "FAILED":
+                any_failed = True
+            lines.append(f"        Ingestion: {ing.status or 'UNKNOWN'}")
+            if ing.started_at:
+                lines.append(f"        Started:   {ing.started_at}")
+            if ing.completed_at:
+                lines.append(f"        Completed: {ing.completed_at}")
+            elif ing.updated_at:
+                lines.append(f"        Updated:   {ing.updated_at}")
+            lines.append(
+                f"        Documents: {ing.scanned or 0} scanned, {ing.indexed or 0} new indexed, "
+                f"{ing.modified or 0} modified, {ing.failed or 0} failed, {ing.deleted or 0} deleted"
+            )
+        else:
+            lines.append("        Ingestion: never run")
+    if kb.gateway_names:
+        lines.append(f"  Gateways:        {', '.join(kb.gateway_names)}")
+        lines.append("  Tools:           retrieve (available)")
+    if any_failed:
+        lines.append("")
+        lines.extend(f"  {h}" for h in FAILURE_HINTS)
+    return lines
+
+
+def format_knowledge_base_summary_line(kb: KbStatusDetail) -> str:
+    """One-line rollup used when no ``--name`` drill-down is requested."""
+    total_indexed = sum((ds.ingestion.indexed or 0) if ds.ingestion else 0 for ds in kb.data_sources)
+    any_failed = any(ds.ingestion and ds.ingestion.status == "FAILED" for ds in kb.data_sources)
+    ingesting = any(
+        ds.ingestion and (ds.ingestion.status or "") in ("IN_PROGRESS", "STARTING", "SUBMITTED")
+        for ds in kb.data_sources
+    )
+    if any_failed:
+        state = "✗ Failed"
+    elif ingesting:
+        state = "⟳ Ingesting"
+    elif kb.status == "ACTIVE":
+        state = "✓ Ready"
+    else:
+        state = kb.status or "Unknown"
+    count = len(kb.data_sources)
+    return f"{kb.name}: {state} ({count} data source{'s' if count != 1 else ''}, {total_indexed} indexed)"
+
+
+__all__ = [
+    "KbDataSourceDetail",
+    "KbIngestionDetail",
+    "KbStatusDetail",
+    "format_knowledge_base_detail",
+    "format_knowledge_base_summary_line",
+]

agentcore/cli/commands/telemetry.py

@@ -0,0 +1,79 @@
+"""`agentcore telemetry` (port of src/cli/commands/telemetry and src/cli/telemetry/config.ts).
+
+The preference is read and stored exactly as upstream so both CLIs agree on it, but this
+port never sends telemetry.
+"""
+
+import os
+from dataclasses import dataclass
+from typing import Literal
+
+import typer
+
+from agentcore.lib.schemas.io.global_config import GlobalConfig, get_global_config_file, read_global_config
+
+DESCRIPTION = "Manage anonymous usage analytics preferences."
+ENV_VAR_NAME = "AGENTCORE_TELEMETRY_DISABLED"
+
+HELP_EPILOG = """\
+Manage Telemetry Preferences:
+  Opt in:   agentcore config telemetry.enabled true
+  Opt out:  agentcore config telemetry.enabled false
+  Status:   agentcore telemetry status
+
+This Python port does not send telemetry; the preference is shared with the npm CLI.
+"""
+
+
+@dataclass(frozen=True)
+class TelemetryPreference:
+    enabled: bool
+    source: Literal["environment", "global-config", "default"]
+    env_var: tuple[str, str] | None = None
+
+
+def resolve_telemetry_preference(config: GlobalConfig | None = None) -> TelemetryPreference:
+    env_value = os.environ.get(ENV_VAR_NAME)
+    if env_value is not None:
+        normalized = env_value.lower().strip()
+        if normalized in ("false", "0"):
+            return TelemetryPreference(True, "environment", (ENV_VAR_NAME, env_value))
+        if normalized:
+            return TelemetryPreference(False, "environment", (ENV_VAR_NAME, env_value))
+
+    if config is None:
+        read = read_global_config()
+        config = read.value if read.success else GlobalConfig()
+    enabled = (config.get("telemetry") or {}).get("enabled")
+    if isinstance(enabled, bool):
+        return TelemetryPreference(enabled, "global-config")
+    return TelemetryPreference(True, "default")
+
+
+def handle_telemetry_status(config_file: str | None = None) -> None:
+    config_file = config_file or get_global_config_file()
+    read = read_global_config(config_file)
+    pref = resolve_telemetry_preference(read.value if read.success else GlobalConfig())
+
+    source_label = {
+        "environment": "environment variable",
+        "global-config": f"global config ({config_file})",
+        "default": "default",
+    }[pref.source]
+
+    typer.echo(f"Telemetry: {'Enabled' if pref.enabled else 'Disabled'}")
+    typer.echo(f"Source: {source_label}")
+    if pref.env_var:
+        name, value = pref.env_var
+        typer.echo(f"\nNote: {name}={value} is set in your environment.")
+    typer.echo("\nThis Python CLI does not send telemetry; the preference applies to the npm CLI.")
+
+
+def register(app: typer.Typer) -> None:
+    telemetry = typer.Typer(help=DESCRIPTION, epilog=HELP_EPILOG, no_args_is_help=True)
+
+    @telemetry.command("status", help="Show current telemetry preference and source")
+    def status() -> None:
+        handle_telemetry_status()
+
+    app.add_typer(telemetry, name="telemetry")