agentcore-cli 0.31.1__py3-none-any.whl

agentcore/cli/commands/invoke/command.py

@@ -0,0 +1,490 @@
+"""`agentcore invoke` (port of commands/invoke/command.tsx)."""
+
+import itertools
+import json
+import os
+import re
+import sys
+import threading
+from typing import Any
+
+import typer
+
+from agentcore.cli.commands.invoke.action import (
+    InvokeContext,
+    handle_harness_invoke_by_arn,
+    handle_invoke,
+    load_invoke_config,
+)
+from agentcore.cli.commands.invoke.constants import INVOKE_DESCRIPTION
+from agentcore.cli.commands.invoke.guards import require_project
+from agentcore.cli.commands.invoke.interactive import run_invoke_interactive
+from agentcore.cli.commands.invoke.resolve_prompt import PromptSources, resolve_prompt
+from agentcore.cli.commands.invoke.types import InvokeOptions, InvokeResult, result
+from agentcore.cli.commands.invoke.validate import validate_invoke_options
+from agentcore.cli.commands.shared.header_utils import parse_header_flags
+from agentcore.cli.errors import get_error_message
+from agentcore.cli.interactive import require_tty
+from agentcore.lib.errors.types import ValidationError
+from agentcore.lib.result import serialize_result
+from agentcore.primitives.base import ADDITIONAL_PARAMS_JSON_ERROR
+
+SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]
+
+HELP_EPILOG = """\
+Payments [non-interactive]
+  --payment-user-id <id>           End-user/wallet-owner identity (defaults to --user-id)
+  --payment-instrument-id <id>     Payment instrument (wallet) ID
+  --payment-session-id <id>        Payment session ID for budget tracking
+  --auto-session                   Auto-create/reuse a payment session for testing
+
+Output [non-interactive]
+  --json                           Output as JSON
+  --stream                         Stream response in real-time
+
+MCP & Advanced [non-interactive]
+  --tool <name>                    MCP tool name (use with "call-tool" prompt)
+  --input <json>                   MCP tool arguments as JSON (use with --tool)
+  --exec                           Execute a shell command in the runtime container
+  --timeout <seconds>              Timeout in seconds for --exec commands
+  -H, --header <header>            Custom header "Name: Value" (repeatable)
+  --bearer-token <token>           Bearer token for CUSTOM_JWT auth (bypasses SigV4)
+
+Harness [non-interactive]
+  --harness <name>                 Select specific harness to invoke
+  --harness-arn <arn>              Invoke a harness by ARN (no project required)
+  --region <region>                AWS region (required with --harness-arn)
+  --verbose                        Print verbose streaming JSON events
+
+Model & Runtime Overrides (harness only) [non-interactive]
+  --model-id <id>                  Override model
+  --model-provider <provider>      bedrock, open_ai, or gemini
+  --api-key-arn <arn>              API key ARN for open_ai/gemini
+  --tools <tools>                  Override tools (comma-separated)
+  --allowed-tools <tools>          Override allowed tools (comma-separated)
+  --skills <paths>                 Skills (comma-separated paths)
+  --system-prompt <text>           Override system prompt
+  --actor-id <id>                  Override memory actor ID
+  --max-iterations <n>             Override max iterations
+  --max-tokens <n>                 Override max tokens
+  --harness-timeout <seconds>      Override timeout seconds
+"""
+
+
+class _Spinner:
+    """stderr spinner (upstream writes it unconditionally, like here)."""
+
+    def __init__(self, message: str):
+        self._message = message
+        self._stop = threading.Event()
+        sys.stderr.write(f"{SPINNER_FRAMES[0]} {message}")
+        sys.stderr.flush()
+        self._thread = threading.Thread(target=self._run, daemon=True)
+        self._thread.start()
+
+    def _run(self) -> None:
+        for frame in itertools.cycle(SPINNER_FRAMES[1:] + SPINNER_FRAMES[:1]):
+            if self._stop.wait(0.08):
+                return
+            sys.stderr.write(f"\r{frame} {self._message}")
+            sys.stderr.flush()
+
+    def stop(self) -> None:
+        self._stop.set()
+        self._thread.join()
+        sys.stderr.write("\r\x1b[K")
+        sys.stderr.flush()
+
+
+def _handle_invoke_cli(options: InvokeOptions, preloaded: InvokeContext | None = None) -> InvokeResult:
+    validation = validate_invoke_options(options)
+    if not validation.valid:
+        return result(False, error=ValidationError(validation.error or "Validation failed"))
+
+    spinner: _Spinner | None = None
+    try:
+        if options.harness_arn:
+            region = options.region or os.environ.get("AWS_REGION") or os.environ.get("AWS_DEFAULT_REGION")
+            if not region:
+                msg = "--region is required with --harness-arn (or set AWS_REGION)"
+                if options.json:
+                    typer.echo(json.dumps({"success": False, "error": msg}, separators=(",", ":")))
+                else:
+                    typer.echo(msg, err=True)
+                raise typer.Exit(1)
+            return handle_harness_invoke_by_arn(options.harness_arn, region, options)
+
+        context = preloaded or load_invoke_config()
+        project = context.project
+        is_harness = options.harness_name is not None or (
+            len(project.harnesses or []) > 0 and len(project.runtimes or []) == 0
+        )
+        if not options.stream and not options.json and not options.exec and not is_harness:
+            spinner = _Spinner("Invoking agent...")
+        out = handle_invoke(context, options)
+        if spinner:
+            spinner.stop()
+            spinner = None
+        return out
+    finally:
+        if spinner:
+            spinner.stop()
+
+
+def redact_sensitive_text(value: str) -> str:
+    # A JWT always begins with `eyJ` (base64url of `{"`); matching by shape never touches prose.
+    value = re.sub(r"eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+", "[REDACTED]", value)
+    value = re.sub(
+        r"""(client[_-]?secret["']?\s*[:=]\s*["']?)([^"',\s}]+)""", r"\1[REDACTED]", value, flags=re.IGNORECASE
+    )
+    value = re.sub(
+        r"""((?:access[_-]?)?token["']?\s*[:=]\s*["']?)([^"',\s}]+)""", r"\1[REDACTED]", value, flags=re.IGNORECASE
+    )
+    return value
+
+
+def _print_invoke_result(res: InvokeResult, as_json: bool | None, stream: bool | None) -> None:
+    if as_json:
+        serialized = serialize_result(res)
+        if isinstance(serialized.get("response"), str):
+            serialized["response"] = redact_sensitive_text(serialized["response"])
+        if isinstance(serialized.get("error"), str):
+            serialized["error"] = redact_sensitive_text(serialized["error"])
+        typer.echo(
+            json.dumps(
+                {k: v for k, v in serialized.items() if v is not None}, separators=(",", ":"), ensure_ascii=False
+            )
+        )
+        return
+
+    def footer() -> None:
+        if res.get("sessionId"):
+            typer.echo(f"\nSession: {res['sessionId']}", err=True)
+            typer.echo(f"To resume: agentcore invoke --session-id {res['sessionId']}", err=True)
+        if res.get("logFilePath"):
+            typer.echo(f"Log: {res['logFilePath']}", err=True)
+
+    if stream:
+        footer()
+        return
+    if res.get("success") and res.get("response"):
+        typer.echo(redact_sensitive_text(res["response"]))
+    elif not res.get("success") and res.get("error") is not None:
+        typer.echo(redact_sensitive_text(str(res["error"])), err=True)
+    footer()
+
+
+def _stdin_piped() -> bool:
+    try:
+        return not sys.stdin.isatty()
+    except (AttributeError, ValueError):
+        return True
+
+
+def _match_runtime_name(name: str | None) -> str | None:
+    """Accept `my-agent` for the runtime `my_agent` (`agentcore init` turns hyphens into underscores)."""
+    if not name or "-" not in name:
+        return name
+    try:
+        from agentcore.lib.schemas.io.config_io import ConfigIO
+
+        runtimes = {r.name for r in ConfigIO().read_project_spec().runtimes or []}
+    except Exception:  # noqa: BLE001 - no project yet; let the normal resolution report it
+        return name
+    candidate = name.replace("-", "_")
+    return candidate if name not in runtimes and candidate in runtimes else name
+
+
+def invoke_command(
+    positional_prompt: str | None = typer.Argument(
+        None,
+        metavar="[PROMPT]",
+        help="Prompt to send to the agent. Also accepts piped stdin when no prompt is provided and stdin is not a "
+        "TTY [non-interactive]",
+        show_default=False,
+    ),
+    prompt: str | None = typer.Option(None, "--prompt", help="Prompt to send to the agent [non-interactive]"),
+    prompt_file: str | None = typer.Option(
+        None,
+        "--prompt-file",
+        help="Read the prompt from a file (for long or structured payloads that exceed shell arg limits) "
+        "[non-interactive]",
+    ),
+    runtime: str | None = typer.Option(
+        None, "--runtime", "--agent-name", help="Select specific runtime [non-interactive]"
+    ),
+    gateway: str | None = typer.Option(None, "--gateway", help="Invoke through a gateway [non-interactive]"),
+    gateway_target_name: str | None = typer.Option(
+        None, "--gateway-target-name", help="HTTP runtime target on the gateway [non-interactive]"
+    ),
+    target: str | None = typer.Option(None, "--target", help="Select deployment target [non-interactive]"),
+    session_id: str | None = typer.Option(
+        None, "--session-id", help="Use specific session ID for conversation continuity"
+    ),
+    user_id: str | None = typer.Option(
+        None, "--user-id", help='User ID for runtime invocation (default: "default-user")'
+    ),
+    as_json: bool = typer.Option(False, "--json", help="Output as JSON [non-interactive]", hidden=True),
+    stream: bool = typer.Option(
+        False, "--stream", help="Stream response in real-time (TUI streams by default) [non-interactive]", hidden=True
+    ),
+    tool: str | None = typer.Option(
+        None, "--tool", help='MCP tool name (use with "call-tool" prompt) [non-interactive]', hidden=True
+    ),
+    input_: str | None = typer.Option(
+        None,
+        "--input",
+        help="Prompt to send to the agent; with --tool, MCP tool arguments as JSON [non-interactive]",
+    ),
+    exec_: bool = typer.Option(
+        False,
+        "--exec",
+        help="Execute a shell command in the runtime container (use `agentcore exec` instead) [non-interactive]",
+        hidden=True,
+    ),
+    timeout: int | None = typer.Option(
+        None, "--timeout", help="Timeout in seconds for --exec commands [non-interactive]", hidden=True
+    ),
+    header: list[str] = typer.Option(
+        [],
+        "-H",
+        "--header",
+        help='Custom header to forward to the agent (format: "Name: Value", repeatable) [non-interactive]',
+        hidden=True,
+    ),
+    bearer_token: str | None = typer.Option(
+        None, "--bearer-token", help="Bearer token for CUSTOM_JWT auth (bypasses SigV4) [non-interactive]", hidden=True
+    ),
+    payment_instrument_id: str | None = typer.Option(
+        None, "--payment-instrument-id", help="Payment instrument ID for x402 payments [non-interactive]", hidden=True
+    ),
+    payment_session_id: str | None = typer.Option(
+        None, "--payment-session-id", help="Payment session ID for budget tracking [non-interactive]", hidden=True
+    ),
+    auto_session: bool = typer.Option(
+        False, "--auto-session", help="Auto-create/reuse a payment session for testing [non-interactive]", hidden=True
+    ),
+    payment_user_id: str | None = typer.Option(
+        None,
+        "--payment-user-id",
+        help="End-user identity (wallet owner) for payments; scopes the instrument/session/budget. Defaults to "
+        "--user-id when omitted.",
+        hidden=True,
+    ),
+    harness: str | None = typer.Option(
+        None, "--harness", help="Select specific harness to invoke [non-interactive]", hidden=True
+    ),
+    harness_arn: str | None = typer.Option(
+        None, "--harness-arn", help="Invoke a harness by ARN (no project required) [non-interactive]", hidden=True
+    ),
+    region: str | None = typer.Option(
+        None, "--region", help="AWS region (required with --harness-arn when no project) [non-interactive]", hidden=True
+    ),
+    verbose: bool = typer.Option(
+        False, "--verbose", help="Print verbose streaming JSON events (harness only) [non-interactive]", hidden=True
+    ),
+    model_id: str | None = typer.Option(
+        None, "--model-id", help="Override model for this invocation (harness only) [non-interactive]", hidden=True
+    ),
+    model_provider: str | None = typer.Option(
+        None,
+        "--model-provider",
+        help="Override model provider: bedrock, open_ai, gemini, lite_llm (harness only) [non-interactive]",
+        hidden=True,
+    ),
+    api_key_arn: str | None = typer.Option(
+        None,
+        "--api-key-arn",
+        help="Override API key ARN for open_ai/gemini (harness only) [non-interactive]",
+        hidden=True,
+    ),
+    api_base: str | None = typer.Option(
+        None, "--api-base", help="Override LiteLLM API base URL (harness only, lite_llm) [non-interactive]"
+    ),
+    additional_params: str | None = typer.Option(
+        None,
+        "--additional-params",
+        help="Override LiteLLM additional params as a JSON object (harness only, lite_llm) [non-interactive]",
+    ),
+    tools: str | None = typer.Option(
+        None, "--tools", help="Override tools, comma-separated (harness only) [non-interactive]", hidden=True
+    ),
+    max_iterations: int | None = typer.Option(
+        None, "--max-iterations", help="Override max iterations (harness only) [non-interactive]", hidden=True
+    ),
+    max_tokens: int | None = typer.Option(
+        None, "--max-tokens", help="Override max tokens (harness only) [non-interactive]", hidden=True
+    ),
+    harness_timeout: int | None = typer.Option(
+        None, "--harness-timeout", help="Override timeout seconds (harness only) [non-interactive]", hidden=True
+    ),
+    skills: str | None = typer.Option(
+        None,
+        "--skills",
+        help="Skills override, comma-separated (path, s3://uri, or https://git-url). Git auth not supported here — "
+        "configure via agentcore add skill [non-interactive]",
+        hidden=True,
+    ),
+    system_prompt: str | None = typer.Option(
+        None, "--system-prompt", help="Override system prompt (harness only) [non-interactive]", hidden=True
+    ),
+    allowed_tools: str | None = typer.Option(
+        None,
+        "--allowed-tools",
+        help="Override allowed tools, comma-separated (harness only) [non-interactive]",
+        hidden=True,
+    ),
+    actor_id: str | None = typer.Option(
+        None, "--actor-id", help="Override memory actor ID (harness only) [non-interactive]", hidden=True
+    ),
+) -> None:
+    try:
+        if not harness_arn:
+            require_project()
+
+        # Load config once (protocol resolution / reuse in the action); failures resurface later.
+        invoke_context: InvokeContext | None = None
+        try:
+            invoke_context = load_invoke_config()
+        except Exception:  # noqa: BLE001, S110
+            pass
+
+        # Python-port convenience: `--input` is the prompt unless it carries MCP tool arguments.
+        if input_ is not None and not tool and prompt is None:
+            prompt, input_ = input_, None
+        runtime = _match_runtime_name(runtime)
+
+        resolved = resolve_prompt(
+            PromptSources(flag=prompt, positional=positional_prompt, file=prompt_file, stdin_piped=_stdin_piped())
+        )
+
+        # Payment flags alone do not force CLI mode: with a prompt they run one-shot, without one they
+        # carry into the interactive flow.
+        cli_mode = (
+            not resolved.success
+            or resolved.prompt is not None
+            or as_json
+            or target
+            or gateway_target_name
+            or stream
+            or runtime
+            or gateway
+            or tool
+            or exec_
+            or bearer_token
+            or harness
+            or harness_arn
+            or verbose
+        )
+        if cli_mode:
+            res = _run_cli(
+                resolved,
+                header=header,
+                additional_params=additional_params,
+                as_json=as_json,
+                invoke_context=invoke_context,
+                options=InvokeOptions(
+                    agent_name=runtime,
+                    gateway=gateway,
+                    gateway_target=gateway_target_name,
+                    target_name=target if target is not None else "default",
+                    session_id=session_id,
+                    user_id=user_id,
+                    json=as_json or None,
+                    stream=stream or None,
+                    tool=tool,
+                    input=input_,
+                    exec=exec_ or None,
+                    timeout=timeout,
+                    bearer_token=bearer_token,
+                    harness_name=harness,
+                    harness_arn=harness_arn,
+                    region=region,
+                    verbose=verbose or None,
+                    model_id=model_id,
+                    model_provider=model_provider,
+                    api_key_arn=api_key_arn,
+                    api_base=api_base,
+                    tools=tools,
+                    max_iterations=max_iterations,
+                    max_tokens=max_tokens,
+                    harness_timeout=harness_timeout,
+                    skills=skills,
+                    system_prompt=system_prompt,
+                    allowed_tools=allowed_tools,
+                    actor_id=actor_id,
+                    payment_instrument_id=payment_instrument_id,
+                    payment_session_id=payment_session_id,
+                    auto_session=auto_session or None,
+                    payment_user_id=payment_user_id,
+                ),
+            )
+            _print_invoke_result(res, as_json, stream)
+            exit_code = res.get("exitCode")
+            raise typer.Exit(exit_code if exit_code is not None else (0 if res.get("success") else 1))
+
+        # Interactive mode. Validate flag combinations before the TTY check.
+        validation = validate_invoke_options(
+            InvokeOptions(auto_session=auto_session or None, payment_session_id=payment_session_id)
+        )
+        if not validation.valid:
+            typer.echo(validation.error, err=True)
+            raise typer.Exit(1)
+
+        require_tty()
+        headers = parse_header_flags(header) if header else None
+        run_invoke_interactive(
+            session_id=session_id,
+            user_id=user_id,
+            headers=headers,
+            bearer_token=bearer_token,
+            payment_instrument_id=payment_instrument_id,
+            payment_session_id=payment_session_id,
+            auto_session=auto_session,
+            payment_user_id=payment_user_id if payment_user_id is not None else user_id,
+        )
+    except typer.Exit:
+        raise
+    except Exception as exc:  # noqa: BLE001 - top-level command boundary, as upstream
+        msg = redact_sensitive_text(get_error_message(exc))
+        if as_json:
+            typer.echo(json.dumps({"success": False, "error": msg}, separators=(",", ":"), ensure_ascii=False))
+        else:
+            typer.echo(f"Error: {msg}")
+        raise typer.Exit(1) from None
+
+
+def _run_cli(
+    resolved: Any,
+    *,
+    header: list[str],
+    additional_params: str | None,
+    as_json: bool,
+    invoke_context: InvokeContext | None,
+    options: InvokeOptions,
+) -> InvokeResult:
+    if not resolved.success:
+        return result(False, error=ValidationError(resolved.error or "Prompt resolution failed"))
+
+    headers = parse_header_flags(header) if header else None
+
+    parsed_params: dict[str, Any] | None = None
+    if additional_params:
+        try:
+            parsed_params = json.loads(additional_params)
+        except ValueError:
+            if as_json:
+                typer.echo(json.dumps({"success": False, "error": ADDITIONAL_PARAMS_JSON_ERROR}, separators=(",", ":")))
+            else:
+                typer.echo(ADDITIONAL_PARAMS_JSON_ERROR, err=True)
+            raise typer.Exit(1) from None
+
+    return _handle_invoke_cli(
+        options.with_(prompt=resolved.prompt, headers=headers, additional_params=parsed_params), invoke_context
+    )
+
+
+def register_invoke(app: typer.Typer) -> None:
+    settings = {"help": INVOKE_DESCRIPTION, "epilog": HELP_EPILOG}
+    app.command("invoke", **settings)(invoke_command)
+    app.command("i", hidden=True, **settings)(invoke_command)

agentcore/cli/commands/invoke/constants.py

@@ -0,0 +1,40 @@
+"""Constants from upstream ``src/cli/constants.ts`` used by `invoke` and `exec`.
+
+Duplicated here (rather than imported from ``agentcore.cli.constants``, owned by another area) so
+these commands don't depend on that module's evolution.
+"""
+
+import os
+import sys
+from typing import Final
+
+INVOKE_DESCRIPTION: Final = "Invoke a deployed agent endpoint."
+EXEC_DESCRIPTION: Final = "Open an interactive shell or run a one-shot command in a deployed agent container."
+
+
+def _styling_enabled() -> bool:
+    if os.environ.get("FORCE_COLOR"):
+        return True
+    return not os.environ.get("NO_COLOR") and sys.stdout.isatty() and sys.stderr.isatty()
+
+
+_STYLING = _styling_enabled()
+
+
+def _style(code: str) -> str:
+    return code if _STYLING else ""
+
+
+class ANSI:
+    """ANSI escape codes for console output; colors are disabled when piped or NO_COLOR is set."""
+
+    red = _style("\x1b[31m")
+    green = _style("\x1b[32m")
+    yellow = _style("\x1b[33m")
+    cyan = _style("\x1b[36m")
+    dim = _style("\x1b[2m")
+    reset = _style("\x1b[0m")
+    clear_line = "\x1b[K"
+    enter_alt_screen = "\x1b[?1049h\x1b[H"
+    exit_alt_screen = "\x1b[?1049l"
+    show_cursor = "\x1b[?25h"

agentcore/cli/commands/invoke/guards.py

@@ -0,0 +1,23 @@
+"""Plain-text port of ``tui/guards/project.tsx`` ``requireProject`` (Ink's FatalError renders to stdout)."""
+
+import os
+
+import typer
+
+from agentcore.lib.schemas.io.path_resolver import find_config_root, get_working_directory
+
+
+def require_project() -> None:
+    cwd = get_working_directory()
+    config_root = find_config_root(cwd)
+    if not config_root:
+        typer.echo("No agentcore project found.")
+        typer.echo("Run agentcore create to fix this.")
+        raise typer.Exit(1)
+    project_root = os.path.realpath(os.path.dirname(config_root))
+    resolved_cwd = os.path.realpath(cwd)
+    if resolved_cwd != project_root:
+        typer.echo("Please run this command from your project root directory.")
+        typer.echo(f"You are in: {resolved_cwd}\nProject root: {project_root}")
+        typer.echo(f"Run cd {project_root} to fix this.")
+        raise typer.Exit(1)