agentcore-cli 0.31.1__py3-none-any.whl

agentcore/cli/commands/invoke/resolve.py

@@ -0,0 +1,149 @@
+"""Port of commands/invoke/resolve.ts: resolve which deployed runtime an invoke targets."""
+
+from dataclasses import dataclass
+from typing import Any
+
+from agentcore.aws._http import encode_uri_component
+from agentcore.cli.commands.invoke import _deps
+from agentcore.lib.errors.types import ResourceNotFoundError, ValidationError
+from agentcore.operations.session import generate_session_id
+
+
+@dataclass
+class ResolveInvokeResult:
+    """``{success: true, ...ResolvedInvokeTarget}`` or ``{success: false, error}``."""
+
+    success: bool
+    error: Exception | None = None
+    agent_spec: Any = None
+    target_name: str | None = None
+    target_config: Any = None
+    region: str | None = None
+    runtime_arn: str | None = None
+    bearer_token: str | None = None
+    session_id: str | None = None
+    baggage: str | None = None
+
+
+def build_config_bundle_baggage(project: Any, target_state: Any, agent_name: str) -> str | None:
+    """W3C baggage for the config bundle whose components reference ``{{runtime:<agent>}}``, if deployed."""
+    key = f"{{{{runtime:{agent_name}}}}}"
+    bundle_spec = next(
+        (b for b in (project.config_bundles or []) if key in (b.components or {})),
+        None,
+    )
+    if bundle_spec is None:
+        return None
+    resources = target_state.resources if target_state else None
+    deployed = (resources.config_bundles if resources else None) or {}
+    state = deployed.get(bundle_spec.name)
+    if state and state.bundle_arn and state.version_id:
+        return (
+            f"aws.agentcore.configbundle_arn={encode_uri_component(state.bundle_arn)},"
+            f"aws.agentcore.configbundle_version={encode_uri_component(state.version_id)}"
+        )
+    return None
+
+
+def resolve_invoke_target(
+    *,
+    project: Any,
+    deployed_state: Any,
+    aws_targets: list[Any],
+    agent_name: str | None = None,
+    target_name: str | None = None,
+    bearer_token: str | None = None,
+    session_id: str | None = None,
+    config_io: Any = None,
+) -> ResolveInvokeResult:
+    targets = deployed_state.targets or {}
+    target_names = list(targets)
+    if not target_names:
+        return ResolveInvokeResult(
+            False, error=ResourceNotFoundError("No deployed targets found. Run `agentcore deploy` first.")
+        )
+
+    selected = target_name if target_name is not None else target_names[0]
+    if target_name and target_name not in target_names:
+        return ResolveInvokeResult(
+            False,
+            error=ResourceNotFoundError(f"Target '{target_name}' not found. Available: {', '.join(target_names)}"),
+        )
+
+    target_state = targets.get(selected)
+    target_config = next((t for t in aws_targets if t.name == selected), None)
+    if target_config is None:
+        return ResolveInvokeResult(
+            False, error=ResourceNotFoundError(f"Target config '{selected}' not found in aws-targets")
+        )
+
+    runtimes = project.runtimes or []
+    if not runtimes:
+        return ResolveInvokeResult(False, error=ValidationError("No agents defined in configuration"))
+
+    agent_names = [a.name for a in runtimes]
+    if not agent_name and len(runtimes) > 1:
+        return ResolveInvokeResult(
+            False,
+            error=ValidationError(f"Multiple runtimes found. Use --runtime to specify one: {', '.join(agent_names)}"),
+        )
+
+    agent_spec = next((a for a in runtimes if a.name == agent_name), None) if agent_name else runtimes[0]
+    if agent_name and agent_spec is None:
+        return ResolveInvokeResult(
+            False,
+            error=ResourceNotFoundError(f"Agent '{agent_name}' not found. Available: {', '.join(agent_names)}"),
+        )
+    if agent_spec is None:
+        return ResolveInvokeResult(False, error=ValidationError("No agents defined in configuration"))
+
+    resources = target_state.resources if target_state else None
+    agent_state = ((resources.runtimes if resources else None) or {}).get(agent_spec.name)
+    if not agent_state:
+        return ResolveInvokeResult(
+            False, error=ValidationError(f"Agent '{agent_spec.name}' is not deployed to target '{selected}'")
+        )
+
+    baggage = build_config_bundle_baggage(project, target_state, agent_spec.name)
+
+    token = bearer_token
+    if agent_spec.authorizer_type == "CUSTOM_JWT" and not token:
+        if _deps.can_fetch_runtime_token(agent_spec.name, config_io=config_io):
+            try:
+                token = _deps.token_of(
+                    _deps.fetch_runtime_token(agent_spec.name, config_io=config_io, deploy_target=selected)
+                )
+            except Exception as exc:  # noqa: BLE001 - surfaced as a validation error, as upstream
+                return ResolveInvokeResult(
+                    False,
+                    error=ValidationError(
+                        f"CUSTOM_JWT agent requires a bearer token. Auto-fetch failed: {exc}\n"
+                        "Provide one manually with --bearer-token.",
+                        cause=exc,
+                    ),
+                )
+        else:
+            return ResolveInvokeResult(
+                False,
+                error=ValidationError(
+                    f"Agent '{agent_spec.name}' is configured for CUSTOM_JWT but no bearer token is available.\n"
+                    "Either provide --bearer-token or re-add the agent with --client-id and --client-secret to "
+                    "enable auto-fetch."
+                ),
+            )
+
+    sid = session_id
+    if token and not sid:
+        sid = generate_session_id()
+
+    return ResolveInvokeResult(
+        True,
+        agent_spec=agent_spec,
+        target_name=selected,
+        target_config=target_config,
+        region=target_config.region,
+        runtime_arn=agent_state.runtime_arn,
+        bearer_token=token,
+        session_id=sid,
+        baggage=baggage,
+    )

agentcore/cli/commands/invoke/resolve_prompt.py

@@ -0,0 +1,60 @@
+"""Port of commands/invoke/resolve-prompt.ts."""
+
+import re
+import sys
+from dataclasses import dataclass
+from typing import IO
+
+
+@dataclass
+class PromptSources:
+    flag: str | None = None
+    """Value from --prompt."""
+    positional: str | None = None
+    file: str | None = None
+    """Path from --prompt-file."""
+    stdin_piped: bool = False
+
+
+@dataclass
+class ResolvedPrompt:
+    success: bool
+    prompt: str | None = None
+    error: str | None = None
+
+
+def _read_prompt_file(path: str) -> ResolvedPrompt:
+    try:
+        with open(path, encoding="utf-8") as f:
+            content = f.read()
+        return ResolvedPrompt(True, prompt=re.sub(r"\r?\n$", "", content, count=1))
+    except OSError as exc:
+        message = f"{exc.strerror}" if exc.strerror else str(exc)
+        if isinstance(exc, FileNotFoundError):
+            message = f"ENOENT: no such file or directory, open '{path}'"
+        return ResolvedPrompt(False, error=f"Failed to read --prompt-file '{path}': {message}")
+
+
+def _read_stdin(stdin: IO[str]) -> str:
+    return stdin.read().strip()
+
+
+def resolve_prompt(sources: PromptSources, stdin: IO[str] | None = None) -> ResolvedPrompt:
+    """Precedence: --prompt, positional, --prompt-file, piped stdin. --prompt-file plus piped stdin is an error."""
+    if sources.flag is not None:
+        return ResolvedPrompt(True, prompt=sources.flag)
+    if sources.positional is not None:
+        return ResolvedPrompt(True, prompt=sources.positional)
+
+    stdin_content = _read_stdin(stdin or sys.stdin) if sources.stdin_piped else ""
+    has_stdin = len(stdin_content) > 0
+
+    if sources.file is not None and has_stdin:
+        return ResolvedPrompt(
+            False, error="Cannot combine --prompt-file with piped stdin. Provide only one prompt source."
+        )
+    if sources.file is not None:
+        return _read_prompt_file(sources.file)
+    if has_stdin:
+        return ResolvedPrompt(True, prompt=stdin_content)
+    return ResolvedPrompt(True, prompt=None)

agentcore/cli/commands/invoke/types.py

@@ -0,0 +1,61 @@
+"""Port of commands/invoke/types.ts."""
+
+from dataclasses import dataclass, replace
+from typing import Any
+
+# Upstream's InvokeResult is `Result & {logFilePath?, agentName?, targetName?, response?, sessionId?, exitCode?}`.
+# It is kept as a plain dict so `--json` output preserves upstream key order (each return site builds
+# the dict in the same order as the upstream object literal; ``None`` means undefined).
+InvokeResult = dict[str, Any]
+
+
+@dataclass
+class InvokeOptions:
+    agent_name: str | None = None
+    harness_name: str | None = None
+    harness_arn: str | None = None
+    """Direct harness ARN — bypasses project config and deployed state resolution."""
+    gateway: str | None = None
+    gateway_target: str | None = None
+    region: str | None = None
+    target_name: str | None = None
+    prompt: str | None = None
+    prompt_file: str | None = None
+    session_id: str | None = None
+    user_id: str | None = None
+    json: bool | None = None
+    stream: bool | None = None
+    tool: str | None = None
+    input: str | None = None
+    exec: bool | None = None
+    timeout: int | None = None
+    headers: dict[str, str] | None = None
+    bearer_token: str | None = None
+    verbose: bool | None = None
+    model_id: str | None = None
+    model_provider: str | None = None
+    api_key_arn: str | None = None
+    api_base: str | None = None
+    additional_params: dict[str, Any] | None = None
+    tools: str | None = None
+    max_iterations: int | None = None
+    harness_timeout: int | None = None
+    max_tokens: int | None = None
+    skills: str | None = None
+    system_prompt: str | None = None
+    allowed_tools: str | None = None
+    actor_id: str | None = None
+    payment_instrument_id: str | None = None
+    payment_session_id: str | None = None
+    auto_session: bool | None = None
+    payment_user_id: str | None = None
+
+    def with_(self, **changes: Any) -> "InvokeOptions":
+        return replace(self, **changes)
+
+
+def result(success: bool, **fields: Any) -> InvokeResult:
+    """Build an InvokeResult dict: ``success`` first, then fields in the given order (``None`` dropped)."""
+    out: InvokeResult = {"success": success}
+    out.update({k: v for k, v in fields.items() if v is not None})
+    return out

agentcore/cli/commands/invoke/validate.py

@@ -0,0 +1,33 @@
+"""Port of commands/invoke/validate.ts."""
+
+from dataclasses import dataclass
+
+from agentcore.cli.commands.invoke.types import InvokeOptions
+
+
+@dataclass
+class ValidationResult:
+    valid: bool
+    error: str | None = None
+
+
+def validate_invoke_options(options: InvokeOptions) -> ValidationResult:
+    if options.exec and not options.prompt:
+        return ValidationResult(False, 'A command is required with --exec. Usage: agentcore invoke --exec "ls -la"')
+    if options.exec and (options.tool or options.input):
+        return ValidationResult(False, "--exec cannot be combined with --tool or --input")
+    if options.exec and options.stream:
+        return ValidationResult(False, "--exec already streams output; --stream is not needed")
+    if options.json and not options.prompt:
+        return ValidationResult(False, "Prompt is required for JSON output")
+    if options.stream and not options.prompt:
+        return ValidationResult(False, "Prompt is required for streaming")
+    if options.auto_session and options.payment_session_id:
+        return ValidationResult(
+            False, "--auto-session and --payment-session-id are mutually exclusive. Use one or the other."
+        )
+    if options.payment_instrument_id is not None and options.payment_instrument_id.strip() == "":
+        return ValidationResult(False, "--payment-instrument-id cannot be empty")
+    if options.payment_session_id is not None and options.payment_session_id.strip() == "":
+        return ValidationResult(False, "--payment-session-id cannot be empty")
+    return ValidationResult(True)

agentcore/cli/commands/job_actions.py

@@ -0,0 +1,239 @@
+"""Job lifecycle commands: `pause`/`resume` (online-eval, online-insights, ab-test), `stop`
+(ab-test, batch-evaluation), `archive` (batch-evaluation, recommendation, ab-test, insights) and
+`promote ab-test` (ports of commands/pause, stop, archive and promote).
+"""
+
+import typer
+
+from agentcore.cli.commands._jobs_common import fail_early, print_json, red, require_project
+from agentcore.cli.errors import get_error_message
+from agentcore.cli.groups import group
+from agentcore.cli.run_command import run_cli_command
+from agentcore.lib import ConfigIO, serialize_result
+from agentcore.operations.eval.pause_resume import handle_pause_resume
+from agentcore.operations.jobs import create_job_engine
+
+# ──────────────────────────────────────────────────────────────────────────────
+# pause / resume
+# ──────────────────────────────────────────────────────────────────────────────
+
+
+def _online_config_action(name: str | None, arn: str | None, region: str | None, as_json: bool, action: str, kind: str):
+    if not arn and not name:
+        fail_early(as_json, "Either a config name or --arn is required")
+    if not arn or name:
+        require_project()
+    past = "Paused" if action == "pause" else "Resumed"
+    try:
+        result = handle_pause_resume(name=name or "", action=action, arn=arn, region=region)
+        if as_json:
+            print_json(serialize_result(result))
+        elif result.success:
+            display = result.value["configId"] if arn else name
+            typer.echo(f'{past} {kind} config "{display}" (status: {result.value["executionStatus"]})')
+        else:
+            red(str(result.error))
+        raise typer.Exit(0 if result.success else 1)
+    except typer.Exit:
+        raise
+    except Exception as exc:  # noqa: BLE001
+        if as_json:
+            print_json({"success": False, "error": get_error_message(exc)})
+        else:
+            red(f"Error: {get_error_message(exc)}")
+        raise typer.Exit(1) from None
+
+
+def _register_pause_resume(action: str) -> None:
+    app = group(action)
+    verb = "Pause" if action == "pause" else "Resume"
+    online_help = (
+        "Pause a deployed online eval config. Use --arn to target configs outside the project."
+        if action == "pause"
+        else "Resume a paused online eval config. Use --arn to target configs outside the project."
+    )
+
+    @app.command("online-eval", help=online_help)
+    def online_eval(
+        name: str | None = typer.Argument(None, help="Config name from project (not needed with --arn)"),
+        arn: str | None = typer.Option(
+            None, "--arn", help="Online eval config ARN — operate without a project directory"
+        ),
+        region: str | None = typer.Option(
+            None, "--region", help="AWS region override (auto-detected from ARN otherwise)"
+        ),
+        as_json: bool = typer.Option(False, "--json", help="Output as JSON"),
+    ) -> None:
+        _online_config_action(name, arn, region, as_json, action, "online eval")
+
+    insights_help = (
+        "[preview] Pause a deployed online insights config. Use --arn to target configs outside the project."
+        if action == "pause"
+        else "[preview] Resume a paused online insights config. Use --arn to target configs outside the project."
+    )
+
+    @app.command("online-insights", help=insights_help)
+    def online_insights(
+        name: str | None = typer.Argument(None, help="Config name from project (not needed with --arn)"),
+        arn: str | None = typer.Option(
+            None, "--arn", help="Online insights config ARN — operate without a project directory"
+        ),
+        region: str | None = typer.Option(
+            None, "--region", help="AWS region override (auto-detected from ARN otherwise)"
+        ),
+        as_json: bool = typer.Option(False, "--json", help="Output as JSON"),
+    ) -> None:
+        _online_config_action(name, arn, region, as_json, action, "online insights")
+
+    @app.command("ab-test", help=f"{verb} a running A/B test")
+    def ab_test(
+        job_id: str = typer.Option(..., "-i", "--id", help="A/B test ID"),
+        region: str | None = typer.Option(None, "--region", help="AWS region (auto-detected if omitted)"),
+        as_json: bool = typer.Option(False, "--json", help="Output as JSON"),
+    ) -> None:
+        require_project()
+
+        def run() -> None:
+            engine = create_job_engine(ConfigIO())
+            result = engine.pause("ab-test", job_id) if action == "pause" else engine.resume("ab-test", job_id)
+            if not result.success:
+                raise result.error
+            if as_json:
+                print_json({"success": True, "id": job_id})
+            else:
+                typer.echo(f"\n✓ A/B test {job_id} {'paused' if action == 'pause' else 'resumed'}.\n")
+
+        run_cli_command(as_json, run)
+
+
+_register_pause_resume("pause")
+_register_pause_resume("resume")
+
+# ──────────────────────────────────────────────────────────────────────────────
+# stop
+# ──────────────────────────────────────────────────────────────────────────────
+
+stop_app = group("stop")
+
+
+def _stop(job_type: str, job_id: str, as_json: bool, label: str) -> None:
+    require_project()
+
+    def run() -> None:
+        result = create_job_engine(ConfigIO()).stop(job_type, job_id)
+        if not result.success:
+            raise result.error
+        if as_json:
+            print_json({"success": True, "id": job_id})
+        else:
+            typer.echo(f"\n✓ {label} {job_id} stop requested.\n")
+
+    run_cli_command(as_json, run)
+
+
+@stop_app.command("ab-test", help="Stop a running A/B test permanently")
+def stop_ab_test(
+    job_id: str = typer.Option(..., "-i", "--id", help="A/B test ID to stop"),
+    region: str | None = typer.Option(None, "--region", help="AWS region (auto-detected if omitted)"),
+    as_json: bool = typer.Option(False, "--json", help="Output as JSON"),
+) -> None:
+    _stop("ab-test", job_id, as_json, "A/B test")
+
+
+@stop_app.command("batch-evaluation", help="Stop a running batch evaluation")
+def stop_batch_evaluation(
+    job_id: str = typer.Option(..., "-i", "--id", help="Batch evaluation ID to stop"),
+    region: str | None = typer.Option(None, "--region", help="AWS region (auto-detected if omitted)"),
+    as_json: bool = typer.Option(False, "--json", help="Output as JSON"),
+) -> None:
+    _stop("batch-evaluation", job_id, as_json, "Batch evaluation")
+
+
+# ──────────────────────────────────────────────────────────────────────────────
+# archive
+# ──────────────────────────────────────────────────────────────────────────────
+
+archive_app = group("archive")
+
+
+def execute_archive(job_type: str, job_id: str, as_json: bool, label: str) -> None:
+    require_project()
+
+    def run() -> None:
+        result = create_job_engine(ConfigIO()).archive(job_type, job_id)
+        if not result.success:
+            raise result.error
+        if as_json:
+            print_json({"success": True, "id": job_id})
+        else:
+            typer.echo(f"\n✓ {label} {job_id} archived.\n")
+
+    run_cli_command(as_json, run)
+
+
+def _register_archive(job_type: str, help_text: str, id_help: str, label: str) -> None:
+    def command(
+        job_id: str = typer.Option(..., "-i", "--id", help=id_help),
+        region: str | None = typer.Option(None, "--region", help="AWS region (auto-detected if omitted)"),
+        as_json: bool = typer.Option(False, "--json", help="Output as JSON"),
+    ) -> None:
+        execute_archive(job_type, job_id, as_json, label)
+
+    archive_app.command(job_type, help=help_text)(command)
+
+
+_register_archive(
+    "batch-evaluation",
+    "Archive a batch evaluation job record on the service and clear local history",
+    "Batch evaluation ID to archive",
+    "Batch evaluation",
+)
+_register_archive(
+    "recommendation",
+    "Archive a recommendation job record on the service and clear local history",
+    "Recommendation ID to archive",
+    "Recommendation",
+)
+_register_archive(
+    "ab-test",
+    "Archive (delete) an A/B test on the service and clear local history",
+    "A/B test ID to archive",
+    "A/B test",
+)
+_register_archive(
+    "insights",
+    "[preview] Archive an insights job record on the service and clear local history",
+    "Insights job ID to archive",
+    "Insights job",
+)
+
+# ──────────────────────────────────────────────────────────────────────────────
+# promote
+# ──────────────────────────────────────────────────────────────────────────────
+
+promote_app = group("promote")
+promote_app.info.help = "Promote resources"
+
+
+@promote_app.command(
+    "ab-test",
+    help="Promote the winning treatment of an A/B test (stops the test and updates agentcore.json)",
+)
+def promote_ab_test(
+    job_id: str = typer.Option(..., "-i", "--id", help="A/B test ID"),
+    region: str | None = typer.Option(None, "--region", help="AWS region (auto-detected if omitted)"),
+    as_json: bool = typer.Option(False, "--json", help="Output as JSON"),
+) -> None:
+    require_project()
+
+    def run() -> None:
+        result = create_job_engine(ConfigIO()).promote("ab-test", job_id)
+        if not result.success:
+            raise result.error
+        if as_json:
+            print_json({"success": True, "id": job_id})
+        else:
+            typer.echo(f"\n✓ A/B test {job_id} stopped and winning variant applied to agentcore.json.")
+            typer.echo("\nRun: agentcore deploy\n")
+
+    run_cli_command(as_json, run)