agentcore-cli 0.31.1__py3-none-any.whl

agentcore/cli/commands/dev/command.py

@@ -0,0 +1,450 @@
+"""Port of commands/dev/command.tsx: `agentcore dev` (alias `d`)."""
+
+import json
+import os
+import subprocess
+import sys
+import threading
+
+import typer
+
+from agentcore.cli.commands.dev._deps import (
+    ANSI_RESET,
+    ANSI_YELLOW,
+    DESCRIPTION,
+    is_deploy_skippable,
+    require_project,
+    run_cli_deploy,
+)
+from agentcore.cli.commands.shared.header_utils import parse_header_flags
+from agentcore.cli.errors import get_error_message
+from agentcore.lib.errors.types import DevServerConnectionError, NoProjectError, ResourceNotFoundError, ValidationError
+from agentcore.lib.schemas.io.path_resolver import find_config_root, get_working_directory
+from agentcore.logging import ExecLogger
+from agentcore.operations.dev import (
+    call_mcp_tool,
+    create_dev_server,
+    find_available_port,
+    get_dev_config,
+    get_dev_port,
+    get_dev_supported_agents,
+    get_endpoint_url,
+    invoke_agent,
+    invoke_agent_streaming,
+    invoke_for_protocol,
+    list_mcp_tools,
+    load_dev_env,
+    load_project_config,
+    on_shutdown_signal,
+    requires_exact_dev_port,
+)
+from agentcore.operations.dev.container_runtime import detect_container_runtime
+from agentcore.operations.dev.dev_server import DevServerCallbacks, DevServerOptions
+from agentcore.operations.dev.invoke_types import InvokeStreamingOptions
+from agentcore.operations.dev.otel import OtelCollector, start_otel_collector
+
+
+def _not_running(port: int, err: BaseException) -> DevServerConnectionError:
+    wrapped = DevServerConnectionError(f"Dev server not running on port {port}. Start it with: agentcore dev --logs")
+    wrapped.__cause__ = err
+    return wrapped
+
+
+def _is_connection_refused(err: BaseException) -> bool:
+    if isinstance(err, DevServerConnectionError):
+        return True
+    msg = str(err) + (str(err.__cause__) if err.__cause__ else "")
+    return "ECONNREFUSED" in msg or "fetch failed" in msg or isinstance(err, ConnectionRefusedError)
+
+
+def _write(chunk: str) -> None:
+    sys.stdout.write(chunk)
+    sys.stdout.flush()
+
+
+def _invoke_dev_server(port: int, prompt: str, stream: bool, headers: dict[str, str] | None) -> None:
+    try:
+        options = InvokeStreamingOptions(port=port, message=prompt, headers=headers)
+        if stream:
+            for chunk in invoke_agent_streaming(options):
+                _write(chunk)
+            _write("\n")
+        else:
+            print(invoke_agent(options))
+    except Exception as err:
+        if _is_connection_refused(err):
+            raise _not_running(port, err) from err
+        raise
+
+
+def _invoke_protocol(protocol: str, port: int, prompt: str, headers: dict[str, str] | None) -> None:
+    try:
+        for chunk in invoke_for_protocol(protocol, InvokeStreamingOptions(port=port, message=prompt, headers=headers)):
+            _write(chunk)
+        _write("\n")
+    except Exception as err:
+        # Upstream only maps connection errors for A2A; AGUI errors propagate as-is.
+        if protocol == "A2A" and _is_connection_refused(err):
+            raise _not_running(port, err) from err
+        raise
+
+
+def _handle_mcp_invoke(
+    port: int, invoke_value: str, tool_name: str | None, input_json: str | None, headers: dict[str, str] | None
+) -> None:
+    try:
+        if invoke_value == "list-tools":
+            tools = list_mcp_tools(port, None, headers).tools
+            if not tools:
+                print("No tools available.")
+                return
+            print("Available tools:")
+            for tool in tools:
+                desc = f" - {tool['description']}" if tool.get("description") else ""
+                print(f"  {tool['name']}{desc}")
+        elif invoke_value == "call-tool":
+            if not tool_name:
+                raise ValidationError(
+                    "--tool is required with call-tool. Usage: agentcore dev call-tool --tool <name> "
+                    '--input \'{"arg": "value"}\''
+                )
+            session_id = list_mcp_tools(port, None, headers).session_id
+            args = {}
+            if input_json:
+                try:
+                    args = json.loads(input_json)
+                except ValueError:
+                    raise ValidationError(
+                        f'Invalid JSON for --input: {input_json}. Expected format: --input \'{{"key": "value"}}\''
+                    ) from None
+            print(call_mcp_tool(port, tool_name, args, session_id, None, headers))
+        else:
+            raise ValidationError(
+                f'Unknown MCP invoke command "{invoke_value}". Usage: agentcore dev list-tools | '
+                "agentcore dev call-tool --tool <name>"
+            )
+    except Exception as err:
+        if _is_connection_refused(err):
+            raise _not_running(port, err) from err
+        raise
+
+
+def _exec_in_container(command: str, container_name: str) -> None:
+    runtime = detect_container_runtime()
+    if runtime is None:
+        raise ResourceNotFoundError("No container runtime found (docker, podman, or finch required)")
+    code = subprocess.call([runtime.binary, "exec", container_name, "bash", "-c", command])
+    if code not in (0,) and code > 0:
+        raise RuntimeError(f"Container exec exited with code {code}")
+
+
+def _parse_port(value: str) -> int:
+    try:
+        port = int(value.strip(), 10)
+    except ValueError:
+        raise ValidationError(f"Invalid port: {value}") from None
+    if not 0 < port < 65536:
+        raise ValidationError(f"Invalid port: {value}")
+    return port
+
+
+def dev_command(
+    ctx: typer.Context,
+    prompt: str | None = typer.Argument(
+        None, metavar="[prompt]", help="Send a prompt to a running dev server [non-interactive]"
+    ),
+    port: str = typer.Option(
+        "8080",
+        "-p",
+        "--port",
+        help="Port for development server. Used as-is when set explicitly; the default is offset by the runtime "
+        "index in multi-runtime projects.",
+    ),
+    runtime: str | None = typer.Option(
+        None, "-r", "--runtime", help="Runtime to run or invoke (required if multiple runtimes)"
+    ),
+    stream: bool = typer.Option(False, "-s", "--stream", help="Stream response when invoking [non-interactive]"),
+    logs: bool = typer.Option(False, "-l", "--logs", help="Run dev server with logs to stdout [non-interactive]"),
+    exec_: bool = typer.Option(
+        False,
+        "--exec",
+        help="Execute a shell command in the running dev container (Container agents only) [non-interactive]",
+    ),
+    tool: str | None = typer.Option(
+        None, "--tool", help='MCP tool name (used with "call-tool" prompt) [non-interactive]'
+    ),
+    input_: str | None = typer.Option(
+        None, "--input", help="MCP tool arguments as JSON (used with --tool) [non-interactive]"
+    ),
+    skip_deploy: bool = typer.Option(
+        False, "--skip-deploy", help="Skip automatic resource deployment before starting dev server"
+    ),
+    header: list[str] = typer.Option(
+        [],
+        "-H",
+        "--header",
+        help='Custom header to forward to the agent (format: "Name: Value", repeatable) [non-interactive]',
+    ),
+    no_browser: bool = typer.Option(False, "-b", "--no-browser", help="Use terminal TUI instead of web-based chat UI"),
+    no_traces: bool = typer.Option(False, "--no-traces", help="Disable local OTEL trace collection"),
+) -> None:
+    try:
+        port_num = _parse_port(port)
+        source = ctx.get_parameter_source("port")
+        port_explicit = getattr(source, "name", None) in ("COMMANDLINE", "ENVIRONMENT")
+        headers = parse_header_flags(header) if header else None
+
+        if exec_:
+            if not prompt:
+                raise ValidationError('A command is required with --exec. Usage: agentcore dev --exec "whoami"')
+            project = load_project_config(get_working_directory())
+            agent_name = runtime or (project.runtimes[0].name if project and project.runtimes else "unknown")
+            target = next((a for a in project.runtimes if a.name == agent_name), None) if project else None
+            if target is None or target.build != "Container":
+                raise ValidationError(
+                    "--exec is only supported for Container build agents. For CodeZip agents, use your terminal to "
+                    "run commands directly."
+                )
+            _exec_in_container(prompt, f"agentcore-dev-{agent_name}".lower())
+            return
+
+        if prompt is not None:
+            _run_invoke(prompt, port_num, port_explicit, runtime, stream, tool, input_, headers)
+            return
+
+        require_project()
+        _run_server(
+            port_num, port_explicit, runtime, logs, skip_deploy, headers, browser=not no_browser, traces=not no_traces
+        )
+        raise typer.Exit(0)
+    except typer.Exit:
+        raise
+    except KeyboardInterrupt:
+        raise typer.Exit(130) from None
+    except Exception as err:  # noqa: BLE001 - top-level command boundary, as upstream
+        print(f"Error: {get_error_message(err)}", file=sys.stderr)
+        raise typer.Exit(1) from None
+
+
+def _run_invoke(
+    prompt: str,
+    port: int,
+    port_explicit: bool,
+    runtime: str | None,
+    stream: bool,
+    tool: str | None,
+    input_json: str | None,
+    headers: dict[str, str] | None,
+) -> None:
+    project = load_project_config(get_working_directory())
+    invoke_port = port
+    target = project.runtimes[0] if project and project.runtimes else None
+    if runtime and project:
+        target = next((a for a in project.runtimes if a.name == runtime), None)
+    elif project and len(project.runtimes) > 1 and not runtime:
+        names = ", ".join(a.name for a in project.runtimes)
+        raise ValidationError(f"Multiple runtimes found. Use --runtime to specify which one. Available: {names}")
+    protocol = (target.protocol if target else None) or "HTTP"
+    if target and project:
+        invoke_port = get_dev_port(project, target.name, protocol, port, port_explicit)
+
+    if protocol == "MCP":
+        _handle_mcp_invoke(invoke_port, prompt, tool, input_json, headers)
+    elif protocol in ("A2A", "AGUI"):
+        _invoke_protocol(protocol, invoke_port, prompt, headers)
+    else:
+        _invoke_dev_server(invoke_port, prompt, stream, headers)
+
+
+def _run_server(
+    port: int,
+    port_explicit: bool,
+    runtime: str | None,
+    logs: bool,
+    skip_deploy: bool,
+    headers: dict[str, str] | None,
+    browser: bool,
+    traces: bool,
+) -> None:
+    working_dir = get_working_directory()
+    project = load_project_config(working_dir)
+    if project is None:
+        raise NoProjectError()
+    has_runtimes = bool(project.runtimes)
+    has_harnesses = bool(project.harnesses)
+    if not has_runtimes and not has_harnesses:
+        raise ValidationError("No agents or harnesses defined in project. Run `agentcore add agent` to fix this.")
+
+    target_dev_agent = (
+        next((a for a in project.runtimes if a.name == runtime), None) if runtime else (project.runtimes or [None])[0]
+    )
+    if target_dev_agent is not None and target_dev_agent.network_mode == "VPC":
+        print(
+            f"{ANSI_YELLOW}Warning: This agent uses VPC network mode. Local dev server runs outside your VPC. "
+            f"Network behavior may differ from deployed environment.{ANSI_RESET}\n"
+        )
+
+    supported = get_dev_supported_agents(project)
+    if not supported and not has_harnesses:
+        raise ValidationError("No agents support dev mode. Dev mode requires an agent with an entrypoint or a harness.")
+
+    config_root = find_config_root(working_dir)
+    otel_env: dict[str, str] = {}
+    collector: OtelCollector | None = None
+    if traces:
+        collector, otel_env = start_otel_collector(os.path.join(config_root or working_dir, ".cli", "traces"))
+
+    try:
+        if logs:
+            _run_logs_mode(
+                project, working_dir, config_root, port, port_explicit, runtime, skip_deploy, otel_env, collector
+            )
+            return
+
+        if not browser:
+            from agentcore.cli.commands.dev.terminal_mode import run_terminal_mode
+
+            run_terminal_mode(working_dir, port, port_explicit, runtime, headers, skip_deploy)
+            return
+
+        from agentcore.cli.commands.dev.browser_mode import (
+            BrowserModeOptions,
+            launch_tui_dev_screen_with_picker,
+            run_browser_mode,
+        )
+
+        is_harness_only = has_harnesses and not supported
+        needs_deploy = is_harness_only and not skip_deploy and not is_deploy_skippable()
+        if needs_deploy:
+            picked = launch_tui_dev_screen_with_picker(working_dir, skip_deploy=skip_deploy)
+            if picked is None:
+                return
+            run_browser_mode(
+                BrowserModeOptions(
+                    working_dir,
+                    project,
+                    port,
+                    port_explicit,
+                    agent_name=picked.get("agentName"),
+                    harness_name=picked.get("harnessName"),
+                    otel_env_vars=otel_env,
+                    collector=collector,
+                )
+            )
+            return
+        run_browser_mode(
+            BrowserModeOptions(
+                working_dir,
+                project,
+                port,
+                port_explicit,
+                agent_name=runtime,
+                otel_env_vars=otel_env,
+                collector=collector,
+            )
+        )
+    finally:
+        if collector is not None:
+            collector.stop()
+
+
+def _run_logs_mode(
+    project, working_dir, config_root, port, port_explicit, runtime, skip_deploy, otel_env, collector
+) -> None:  # type: ignore[no-untyped-def]
+    supported = get_dev_supported_agents(project)
+    has_harnesses = bool(project.harnesses)
+    if not supported and has_harnesses:
+        if not skip_deploy:
+            run_cli_deploy()
+        print("Harness dev runs against the deployed service (no local server).")
+        print("If you changed the harness config, redeploy to pick up changes: agentcore deploy")
+        print("\nInvoke your harness:")
+        for harness in project.harnesses:
+            print(f'  agentcore invoke --harness {harness.name} "your prompt"')
+        print("\nOr use the interactive TUI: agentcore dev")
+        return
+
+    if len(project.runtimes) > 1 and not runtime:
+        names = ", ".join(a.name for a in project.runtimes)
+        raise ValidationError(f"Multiple runtimes found. Use --runtime to specify which one. Available: {names}")
+
+    agent_name = runtime or (project.runtimes[0].name if project.runtimes else None)
+    selected = next((r for r in project.runtimes if r.name == agent_name), None)
+    env_vars = {**load_dev_env(working_dir, selected).env_vars, **otel_env}
+    config = get_dev_config(working_dir, project, config_root, agent_name)
+    if config is None:
+        raise ValidationError("No dev-supported agents found.")
+
+    exact = requires_exact_dev_port(config.protocol)
+    target_port = get_dev_port(project, config.agent_name, config.protocol, port, port_explicit)
+    if config.protocol != "MCP" and not port_explicit and target_port != port:
+        idx = [a.name for a in project.runtimes].index(config.agent_name)
+        print(
+            f'Runtime "{config.agent_name}" is at index {idx}; using port {target_port} '
+            f"(pass --port {target_port} to override)."
+        )
+    actual_port = find_available_port(target_port)
+    if exact and actual_port != target_port:
+        raise ValidationError(f"Port {target_port} is in use. {config.protocol} agents require port {target_port}.")
+    if not exact and port_explicit and actual_port != target_port:
+        raise ValidationError(
+            f"Port {target_port} is in use. Free it or pass a different --port (no port is chosen automatically "
+            "when --port is set explicitly)."
+        )
+    if not skip_deploy and has_harnesses:
+        run_cli_deploy()
+
+    logger = ExecLogger(command="dev")
+    if actual_port != target_port:
+        print(f"Port {target_port} in use, using {actual_port}")
+    print("Starting dev server...")
+    print(f"Agent: {config.agent_name}")
+    if config.protocol != "MCP":
+        print("Provider: (see agent code)")
+    if config.protocol != "HTTP":
+        print(f"Protocol: {config.protocol}")
+    print(f"Server: {get_endpoint_url(actual_port, config.protocol)}")
+    print(f"Log: {logger.get_relative_log_path()}")
+    print("Press Ctrl+C to stop\n", flush=True)
+
+    done = threading.Event()
+    exit_code: list[int | None] = [None]
+
+    def on_log(level: str, msg: str) -> None:
+        prefix = "❌" if level == "error" else "⚠️" if level == "warn" else "→"
+        print(f"{prefix} {msg}", flush=True)
+        logger.log(msg, "error" if level == "error" else "info")
+
+    def on_exit(code: int | None) -> None:
+        print(f"\nServer exited with code {code if code is not None else 0}", flush=True)
+        logger.finalize(code == 0)
+        exit_code[0] = code
+        done.set()
+
+    server = create_dev_server(
+        config, DevServerOptions(port=actual_port, env_vars=env_vars, callbacks=DevServerCallbacks(on_log, on_exit))
+    )
+
+    def shutdown() -> None:
+        print("\nStopping server...", flush=True)
+        if collector is not None:
+            collector.stop()
+        server.kill()
+
+    on_shutdown_signal(shutdown)
+    server.start()
+    try:
+        while not done.wait(0.5):
+            pass
+    except KeyboardInterrupt:
+        shutdown()
+        done.wait(5)
+    code = exit_code[0]
+    if code not in (0, None):
+        raise RuntimeError(f"Server exited with code {code}")
+
+
+def register(app: typer.Typer) -> None:
+    settings = {"help_option_names": ["-h", "--help"]}
+    app.command("dev", help=DESCRIPTION, context_settings=settings)(dev_command)
+    app.command("d", help=DESCRIPTION, hidden=True, context_settings=settings)(dev_command)