agentcore-cli 0.31.1__py3-none-any.whl

agentcore/operations/dev/server.py

@@ -0,0 +1,28 @@
+"""Port of operations/dev/server.ts: dev server barrel + factory."""
+
+from agentcore.operations.dev.codezip_dev_server import CodeZipDevServer
+from agentcore.operations.dev.config import DevConfig
+from agentcore.operations.dev.container_dev_server import ContainerDevServer
+from agentcore.operations.dev.dev_server import DevServer, DevServerCallbacks, DevServerOptions, LogLevel
+from agentcore.operations.dev.utils import find_available_port, wait_for_port, wait_for_server_ready
+
+
+def create_dev_server(config: DevConfig, options: DevServerOptions) -> DevServer:
+    """Container builds run in Docker/Podman/Finch; everything else runs as a local process."""
+    if config.build_type == "Container":
+        return ContainerDevServer(config, options)
+    return CodeZipDevServer(config, options)
+
+
+__all__ = [
+    "CodeZipDevServer",
+    "ContainerDevServer",
+    "DevServer",
+    "DevServerCallbacks",
+    "DevServerOptions",
+    "LogLevel",
+    "create_dev_server",
+    "find_available_port",
+    "wait_for_port",
+    "wait_for_server_ready",
+]

agentcore/operations/dev/sse_transform.py

@@ -0,0 +1,30 @@
+"""Port of operations/dev/sse-transform.ts: normalize an agent SSE stream for the browser."""
+
+import codecs
+import json
+from collections.abc import Callable, Iterable
+
+from agentcore.operations.dev.invoke import parse_sse_line
+
+
+def _emit(line: str, write: Callable[[str], None]) -> None:
+    content, error = parse_sse_line(line)
+    if error:
+        write(f"data: {json.dumps({'error': error}, ensure_ascii=False, separators=(',', ':'))}\n\n")
+    elif content:
+        write(f"data: {json.dumps(content, ensure_ascii=False)}\n\n")
+
+
+def pipe_sse_transformed(chunks: Iterable[bytes], write: Callable[[str], None], end: Callable[[], None]) -> None:
+    """Re-emit each ``data:`` event as ``data: "text"`` (or ``data: {"error": ...}``), then end."""
+    decoder = codecs.getincrementaldecoder("utf-8")(errors="replace")
+    buffer = ""
+    for chunk in chunks:
+        buffer += decoder.decode(chunk)
+        lines = buffer.split("\n")
+        buffer = lines.pop()
+        for line in lines:
+            _emit(line, write)
+    if buffer:
+        _emit(buffer, write)
+    end()

agentcore/operations/dev/utils.py

@@ -0,0 +1,152 @@
+"""Port of operations/dev/utils.ts: port probing, readiness polling and display helpers."""
+
+import signal
+import socket
+import threading
+import time
+import webbrowser
+from collections.abc import Callable
+from typing import Any
+
+
+def _check_port(port: int, host: str) -> bool:
+    """True if ``port`` can be bound on ``host`` (mirrors net.createServer().listen)."""
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    try:
+        # Node's listen() sets SO_REUSEADDR on POSIX; do the same so TIME_WAIT sockets don't count.
+        if hasattr(socket, "SO_REUSEADDR"):
+            sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        sock.bind((host, port))
+        sock.listen(1)
+        return True
+    except OSError:
+        return False
+    finally:
+        sock.close()
+
+
+def is_port_available(port: int) -> bool:
+    """Available on both 127.0.0.1 and 0.0.0.0 (checked sequentially, as upstream)."""
+    if not _check_port(port, "127.0.0.1"):
+        return False
+    return _check_port(port, "0.0.0.0")
+
+
+def find_available_port(start_port: int) -> int:
+    port = start_port
+    while not is_port_available(port):
+        port += 1
+    return port
+
+
+def wait_for_port(port: int, timeout_ms: int = 3000) -> bool:
+    """Wait for ``port`` to become free."""
+    start = time.monotonic()
+    while (time.monotonic() - start) * 1000 < timeout_ms:
+        if is_port_available(port):
+            return True
+        time.sleep(0.1)
+    return False
+
+
+def _is_listening(port: int) -> bool:
+    try:
+        with socket.create_connection(("127.0.0.1", port), timeout=1):
+            return True
+    except OSError:
+        return False
+
+
+def wait_for_server_ready(port: int, timeout_ms: int = 60000) -> bool:
+    """Wait until something accepts connections on 127.0.0.1:``port``."""
+    start = time.monotonic()
+    while (time.monotonic() - start) * 1000 < timeout_ms:
+        if _is_listening(port):
+            return True
+        time.sleep(0.5)
+    return False
+
+
+def sleep(ms: float) -> None:
+    time.sleep(ms / 1000)
+
+
+def get_endpoint_url(port: int, protocol: str) -> str:
+    if protocol == "MCP":
+        return f"http://localhost:{port}/mcp"
+    if protocol == "A2A":
+        return f"http://localhost:{port}/"
+    return f"http://localhost:{port}/invocations"
+
+
+def format_mcp_tool_list(tools: list[dict[str, Any]]) -> str:
+    lines = []
+    for t in tools:
+        props = (t.get("inputSchema") or {}).get("properties")
+        params = (
+            ", ".join(f"{name}: {(schema or {}).get('type') or 'any'}" for name, schema in props.items())
+            if props
+            else ""
+        )
+        desc = f" - {t['description']}" if t.get("description") else ""
+        lines.append(f"  {t['name']}({params}){desc}")
+    joined = "\n".join(lines)
+    return (
+        f"Available tools ({len(tools)}):\n{joined}\n\n"
+        'Type: tool_name {"arg": "value"} to call a tool. Type "list" to refresh.'
+    )
+
+
+class FetchFailedError(ConnectionError):
+    """Raised when a local HTTP request cannot connect (Node's ``TypeError: fetch failed``)."""
+
+    def __init__(self, cause: BaseException | None = None):
+        super().__init__("fetch failed")
+        self.__cause__ = cause
+
+
+def is_connection_error(error: BaseException) -> bool:
+    """Only network-level failures (connection refused / fetch failed), not application errors."""
+    message = str(error)
+    return (
+        isinstance(error, (FetchFailedError, ConnectionRefusedError))
+        or "ECONNREFUSED" in message
+        or (message == "fetch failed")
+    )
+
+
+def convert_entrypoint_to_module(entrypoint: str) -> str:
+    if ":" in entrypoint:
+        return entrypoint
+    path = entrypoint.removesuffix(".py")
+    return f"{path.replace('/', '.')}:app"
+
+
+def on_shutdown_signal(handler: Callable[[], None]) -> None:
+    """Run ``handler`` once on the first SIGINT/SIGTERM (``process.once`` semantics)."""
+    fired = threading.Event()
+    previous: dict[int, Any] = {}
+
+    def _handle(signum: int, _frame: Any) -> None:
+        for sig, prev in previous.items():
+            try:
+                signal.signal(sig, prev)
+            except (ValueError, OSError):
+                pass
+        if not fired.is_set():
+            fired.set()
+            handler()
+
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        try:
+            previous[sig] = signal.getsignal(sig)
+            signal.signal(sig, _handle)
+        except (ValueError, OSError):  # not the main thread
+            pass
+
+
+def open_browser(url: str) -> None:
+    try:
+        webbrowser.open(url)
+    except Exception:  # noqa: BLE001 - best effort, like the detached spawn upstream
+        pass

agentcore/operations/dev/web_ui/__init__.py

@@ -0,0 +1,31 @@
+"""Local web UI server for `agentcore dev` (port of operations/dev/web-ui)."""
+
+from agentcore.operations.dev.web_ui.constants import (
+    WEB_UI_DEFAULT_PORT,
+    WEB_UI_LOCAL_URL,
+    AgentError,
+    AgentInfo,
+    HarnessInfo,
+)
+from agentcore.operations.dev.web_ui.run_web_ui import run_web_ui
+from agentcore.operations.dev.web_ui.web_server import (
+    CSP_HEADER,
+    RunningAgent,
+    WebUIOptions,
+    WebUIServer,
+    resolve_ui_dist_dir,
+)
+
+__all__ = [
+    "CSP_HEADER",
+    "WEB_UI_DEFAULT_PORT",
+    "WEB_UI_LOCAL_URL",
+    "AgentError",
+    "AgentInfo",
+    "HarnessInfo",
+    "RunningAgent",
+    "WebUIOptions",
+    "WebUIServer",
+    "resolve_ui_dist_dir",
+    "run_web_ui",
+]

agentcore/operations/dev/web_ui/constants.py

@@ -0,0 +1,25 @@
+"""Port of operations/dev/web-ui/constants.ts."""
+
+from dataclasses import dataclass
+from typing import Any
+
+WEB_UI_LOCAL_URL = "http://localhost:5173"
+
+# Default port for the web UI proxy server. Agent ports start above this.
+WEB_UI_DEFAULT_PORT = 8081
+
+# Metadata about an available agent: {"name", "buildType", "protocol", "runtimeIndex"?} (StatusAgent).
+AgentInfo = dict[str, Any]
+
+
+@dataclass
+class AgentError:
+    message: str
+    timestamp: int
+
+
+@dataclass
+class HarnessInfo:
+    name: str
+    harness_arn: str
+    region: str

agentcore/operations/dev/web_ui/handlers/__init__.py

@@ -0,0 +1,36 @@
+"""Web UI route handlers (port of operations/dev/web-ui/handlers). The RouteContext is the WebUIServer."""
+
+from agentcore.operations.dev.web_ui.handlers.a2a_proxy import handle_a2a_agent_card
+from agentcore.operations.dev.web_ui.handlers.cloudwatch_traces import (
+    handle_get_cloud_watch_trace,
+    handle_list_cloud_watch_traces,
+)
+from agentcore.operations.dev.web_ui.handlers.harness_invocation import (
+    handle_harness_invocation,
+    handle_harness_tool_response,
+)
+from agentcore.operations.dev.web_ui.handlers.invocations import handle_invocations
+from agentcore.operations.dev.web_ui.handlers.mcp_proxy import handle_mcp_proxy
+from agentcore.operations.dev.web_ui.handlers.memory import handle_list_memory_records, handle_retrieve_memory_records
+from agentcore.operations.dev.web_ui.handlers.resources import handle_resources
+from agentcore.operations.dev.web_ui.handlers.start import handle_start, resolve_agent_target_port
+from agentcore.operations.dev.web_ui.handlers.status import handle_status
+from agentcore.operations.dev.web_ui.handlers.traces import handle_get_trace, handle_list_traces
+
+__all__ = [
+    "handle_a2a_agent_card",
+    "handle_get_cloud_watch_trace",
+    "handle_get_trace",
+    "handle_harness_invocation",
+    "handle_harness_tool_response",
+    "handle_invocations",
+    "handle_list_cloud_watch_traces",
+    "handle_list_memory_records",
+    "handle_list_traces",
+    "handle_mcp_proxy",
+    "handle_resources",
+    "handle_retrieve_memory_records",
+    "handle_start",
+    "handle_status",
+    "resolve_agent_target_port",
+]

agentcore/operations/dev/web_ui/handlers/_common.py

@@ -0,0 +1,36 @@
+"""Shared helpers for web UI route handlers (RouteContext is the WebUIServer)."""
+
+import math
+from typing import Any
+
+from agentcore.operations.dev._server import Response, js_dumps
+
+
+def send_json(ctx: Any, res: Response, origin: str | None, status: int, body: Any, cors: bool = True) -> None:
+    if cors:
+        ctx.set_cors_headers(res, origin)
+    res.write_head(status, {"Content-Type": "application/json"})
+    res.end(js_dumps(body))
+
+
+def parse_time_params(
+    ctx: Any, res: Response, origin: str | None, param: Any
+) -> tuple[bool, float | None, float | None]:
+    """Optional startTime/endTime epoch-ms query params; sends a 400 and returns ok=False if invalid."""
+    values: list[float | None] = []
+    for key in ("startTime", "endTime"):
+        raw = param(key)
+        if not raw:
+            values.append(None)
+            continue
+        try:
+            number = float(raw)
+            if math.isnan(number):
+                raise ValueError
+        except ValueError:
+            send_json(
+                ctx, res, origin, 400, {"success": False, "error": f"{key} must be a number (epoch milliseconds)"}
+            )
+            return False, None, None
+        values.append(int(number) if number.is_integer() else number)
+    return True, values[0], values[1]

agentcore/operations/dev/web_ui/handlers/_deployed.py

@@ -0,0 +1,37 @@
+"""Shared config loading + target resolution for ``?target=deployed`` routes."""
+
+from typing import Any
+
+from agentcore.lib.schemas.io.config_io import ConfigIO
+from agentcore.operations.dev._server import Response
+from agentcore.operations.dev.web_ui.handlers._common import send_json
+
+
+def resolve_deployed(
+    ctx: Any, res: Response, origin: str | None, agent_name: str | None, target_name: str | None, session_id: str | None
+) -> Any | None:
+    """Return the resolved invoke target, or None after sending the error response."""
+    config_io = ConfigIO(base_dir=ctx.options.config_root)
+    try:
+        project = config_io.read_project_spec()
+        deployed_state = config_io.read_deployed_state()
+        aws_targets = config_io.read_aws_deployment_targets()
+    except Exception as err:  # noqa: BLE001
+        send_json(ctx, res, origin, 500, {"success": False, "error": f"Failed to load config: {err}"})
+        return None
+
+    from agentcore.cli.commands.invoke.resolve import resolve_invoke_target
+
+    resolved = resolve_invoke_target(
+        project=project,
+        deployed_state=deployed_state,
+        aws_targets=aws_targets,
+        agent_name=agent_name,
+        target_name=target_name,
+        session_id=session_id,
+        config_io=config_io,
+    )
+    if not resolved.success:
+        send_json(ctx, res, origin, 400, {"success": False, "error": str(resolved.error)})
+        return None
+    return resolved

agentcore/operations/dev/web_ui/handlers/a2a_proxy.py

@@ -0,0 +1,37 @@
+"""GET /api/a2a/agent-card (port of handlers/a2a-proxy.ts)."""
+
+from typing import Any
+
+from agentcore.operations.dev._http import fetch
+from agentcore.operations.dev._server import Request, Response
+from agentcore.operations.dev.web_ui.handlers._common import send_json
+
+
+def handle_a2a_agent_card(ctx: Any, req: Request, res: Response, origin: str | None = None) -> None:
+    from agentcore.operations.dev.web_ui.web_server import parse_request_url
+
+    ctx.set_cors_headers(res, origin)
+    _, param = parse_request_url(req)
+    agent_name = param("agentName")
+    if not agent_name:
+        send_json(ctx, res, origin, 400, {"success": False, "error": "agentName query parameter is required"}, False)
+        return
+    running = ctx.running_agents.get(agent_name)
+    if not running:
+        send_json(ctx, res, origin, 400, {"success": False, "error": f'Agent "{agent_name}" is not running'}, False)
+        return
+    try:
+        headers = {"Accept": "application/json"}
+        card_res = fetch(f"http://localhost:{running.port}/.well-known/agent-card.json", headers=headers)
+        if card_res.status == 404:
+            card_res.close()
+            card_res = fetch(f"http://localhost:{running.port}/.well-known/agent.json", headers=headers)
+        if not card_res.ok:
+            card_res.close()
+            error = f"Agent card not available ({card_res.status})"
+            send_json(ctx, res, origin, 502, {"success": False, "error": error}, False)
+            return
+        card = card_res.json()
+        send_json(ctx, res, origin, 200, {"success": True, "card": card}, False)
+    except Exception as err:  # noqa: BLE001
+        send_json(ctx, res, origin, 502, {"success": False, "error": f"Failed to fetch agent card: {err}"}, False)

agentcore/operations/dev/web_ui/handlers/cloudwatch_traces.py

@@ -0,0 +1,71 @@
+"""GET /api/cloudwatch-traces[/:traceId] (port of handlers/cloudwatch-traces.ts)."""
+
+import re
+from typing import Any
+
+from agentcore.operations.dev._server import Request, Response
+from agentcore.operations.dev.web_ui.handlers._common import parse_time_params, send_json
+
+_ONE_OF = "Either agentName or harnessName query parameter is required"
+_NOT_BOTH = "Provide either agentName or harnessName, not both"
+
+
+def _check_target(ctx: Any, res: Response, origin: str | None, agent: str | None, harness: str | None) -> bool:
+    if not agent and not harness:
+        send_json(ctx, res, origin, 400, {"success": False, "error": _ONE_OF})
+        return False
+    if agent and harness:
+        send_json(ctx, res, origin, 400, {"success": False, "error": _NOT_BOTH})
+        return False
+    return True
+
+
+def handle_list_cloud_watch_traces(ctx: Any, req: Request, res: Response, origin: str | None = None) -> None:
+    from agentcore.operations.dev.web_ui.web_server import parse_request_url
+
+    _, param = parse_request_url(req)
+    handler = ctx.options.on_list_cloud_watch_traces
+    if not handler:
+        send_json(ctx, res, origin, 404, {"success": False, "error": "CloudWatch traces are not available"})
+        return
+    agent, harness = param("agentName"), param("harnessName")
+    if not _check_target(ctx, res, origin, agent, harness):
+        return
+    ok, start, end = parse_time_params(ctx, res, origin, param)
+    if not ok:
+        return
+    try:
+        result = handler(agent, harness, start, end)
+        send_json(ctx, res, origin, 200 if result.get("success") else 500, result)
+    except Exception as err:  # noqa: BLE001
+        ctx.log("error", f"List CloudWatch traces error: {err}")
+        send_json(ctx, res, origin, 500, {"success": False, "error": "Failed to list CloudWatch traces"})
+
+
+def handle_get_cloud_watch_trace(ctx: Any, req: Request, res: Response, origin: str | None = None) -> None:
+    from agentcore.operations.dev.web_ui.web_server import parse_request_url
+
+    pathname, param = parse_request_url(req)
+    handler = ctx.options.on_get_cloud_watch_trace
+    if not handler:
+        send_json(ctx, res, origin, 404, {"success": False, "error": "CloudWatch traces are not available"})
+        return
+    trace_id = pathname.replace("/api/cloudwatch-traces/", "", 1)
+    agent, harness = param("agentName"), param("harnessName")
+    if not trace_id:
+        send_json(ctx, res, origin, 400, {"success": False, "error": "traceId is required in the URL path"})
+        return
+    if not re.fullmatch(r"[a-fA-F0-9-]+", trace_id):
+        send_json(ctx, res, origin, 400, {"success": False, "error": "Invalid trace ID format"})
+        return
+    if not _check_target(ctx, res, origin, agent, harness):
+        return
+    ok, start, end = parse_time_params(ctx, res, origin, param)
+    if not ok:
+        return
+    try:
+        result = handler(agent, harness, trace_id, start, end)
+        send_json(ctx, res, origin, 200 if result.get("success") else 500, result)
+    except Exception as err:  # noqa: BLE001
+        ctx.log("error", f"Get CloudWatch trace error: {err}")
+        send_json(ctx, res, origin, 500, {"success": False, "error": "Failed to get CloudWatch trace"})

agentcore/operations/dev/web_ui/handlers/harness_invocation.py

@@ -0,0 +1,89 @@
+"""Harness invocation over SSE (port of handlers/harness-invocation.ts and harness-tool-response.ts)."""
+
+import json
+import uuid
+from typing import Any
+
+from agentcore.operations.dev._server import Request, Response, js_dumps
+from agentcore.operations.dev.web_ui.handlers._common import send_json
+from agentcore.operations.dev.web_ui.handlers.harness_utils import build_invoke_options, read_local_harness_model
+
+
+def _invoke_harness(**kwargs: Any):  # type: ignore[no-untyped-def]
+    from agentcore.aws import agentcore_harness
+
+    return agentcore_harness.invoke_harness(**kwargs)
+
+
+def _stream_harness(ctx: Any, res: Response, origin: str | None, session_id: str, invoke_opts: dict[str, Any]) -> None:
+    ctx.set_cors_headers(res, origin)
+    res.write_head(
+        200,
+        {
+            "Content-Type": "text/event-stream",
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+            "x-session-id": session_id,
+        },
+    )
+    try:
+        for event in _invoke_harness(**invoke_opts):
+            res.write(f"data: {js_dumps(event)}\n\n")
+    except Exception as err:  # noqa: BLE001 - surfaced to the browser as an SSE error event
+        res.write(f"data: {js_dumps({'type': 'error', 'errorType': 'invocationError', 'message': str(err)})}\n\n")
+    res.end()
+
+
+def _find_harness(ctx: Any, name: str) -> Any | None:
+    return next((h for h in ctx.options.harnesses or [] if h.name == name), None)
+
+
+def handle_harness_invocation(ctx: Any, body: dict[str, Any], res: Response, origin: str | None = None) -> None:
+    harness_name = body.get("harnessName")
+    prompt = body.get("prompt")
+    if not harness_name or not prompt:
+        error = "harnessName is required" if not harness_name else "prompt is required"
+        send_json(ctx, res, origin, 400, {"success": False, "error": error})
+        return
+    session_id = body.get("sessionId") or str(uuid.uuid4())
+    harness = _find_harness(ctx, harness_name)
+    if harness is None:
+        send_json(ctx, res, origin, 404, {"success": False, "error": f'Harness "{harness_name}" not found'})
+        return
+    messages = [{"role": "user", "content": [{"text": prompt}]}]
+    spec_model = read_local_harness_model(ctx.options.config_root, harness_name)
+    opts = build_invoke_options(
+        harness.harness_arn, harness.region, session_id, messages, body.get("harnessOverrides"), spec_model
+    )
+    _stream_harness(ctx, res, origin, session_id, opts)
+
+
+def handle_harness_tool_response(ctx: Any, req: Request, res: Response, origin: str | None = None) -> None:
+    body = ctx.read_body(req)
+    try:
+        raw = json.loads(body)
+        if not isinstance(raw, dict):
+            raise ValueError
+    except ValueError:
+        send_json(ctx, res, origin, 400, {"success": False, "error": "Invalid JSON"})
+        return
+    if not raw.get("harnessName"):
+        error = "harnessName is required"
+    elif not raw.get("messages") or not isinstance(raw.get("messages"), list):
+        error = "messages array is required"
+    elif not raw.get("sessionId"):
+        error = "sessionId is required"
+    else:
+        error = None
+    if error:
+        send_json(ctx, res, origin, 400, {"success": False, "error": error})
+        return
+    harness = _find_harness(ctx, raw["harnessName"])
+    if harness is None:
+        send_json(ctx, res, origin, 404, {"success": False, "error": f'Harness "{raw["harnessName"]}" not found'})
+        return
+    spec_model = read_local_harness_model(ctx.options.config_root, raw["harnessName"])
+    opts = build_invoke_options(
+        harness.harness_arn, harness.region, raw["sessionId"], raw["messages"], raw.get("harnessOverrides"), spec_model
+    )
+    _stream_harness(ctx, res, origin, raw["sessionId"], opts)

agentcore/operations/dev/web_ui/handlers/harness_utils.py

@@ -0,0 +1,95 @@
+"""Port of handlers/harness-utils.ts: build InvokeHarness kwargs for dev invocations."""
+
+from typing import Any
+
+from agentcore.lib.schemas.io.config_io import ConfigIO
+
+DEFAULT_MAX_ITERATIONS = 75
+
+
+def build_model_override(spec_model: Any) -> dict[str, Any] | None:
+    """Map the local harness spec's model onto the invoke API's model configuration."""
+    common: dict[str, Any] = {"modelId": spec_model.model_id}
+    if spec_model.temperature is not None:
+        common["temperature"] = spec_model.temperature
+    if spec_model.top_p is not None:
+        common["topP"] = spec_model.top_p
+    if spec_model.max_tokens is not None:
+        common["maxTokens"] = spec_model.max_tokens
+    provider = spec_model.provider
+    if provider == "bedrock":
+        return {
+            "bedrockModelConfig": {**common, **({"apiFormat": spec_model.api_format} if spec_model.api_format else {})}
+        }
+    if provider == "open_ai":
+        extra: dict[str, Any] = {}
+        if spec_model.api_key_arn:
+            extra["apiKeyArn"] = spec_model.api_key_arn
+        if spec_model.api_format and spec_model.api_format != "converse_stream":
+            extra["apiFormat"] = spec_model.api_format
+        return {"openAiModelConfig": {**common, **extra}}
+    if provider == "gemini":
+        extra = {}
+        if spec_model.api_key_arn:
+            extra["apiKeyArn"] = spec_model.api_key_arn
+        if spec_model.top_k is not None:
+            extra["topK"] = spec_model.top_k
+        return {"geminiModelConfig": {**common, **extra}}
+    if provider == "lite_llm":
+        extra = {}
+        if spec_model.api_key_arn:
+            extra["apiKeyArn"] = spec_model.api_key_arn
+        if spec_model.api_base:
+            extra["apiBase"] = spec_model.api_base
+        if spec_model.additional_params:
+            extra["additionalParams"] = spec_model.additional_params
+        return {"liteLlmModelConfig": {**common, **extra}}
+    return None
+
+
+def read_local_harness_model(config_root: str | None, harness_name: str) -> Any | None:
+    if not config_root:
+        return None
+    try:
+        return ConfigIO(base_dir=config_root).read_harness_spec(harness_name).model
+    except Exception:  # noqa: BLE001 - best effort, as upstream
+        return None
+
+
+def build_invoke_options(
+    harness_arn: str,
+    region: str,
+    session_id: str,
+    messages: list[dict[str, Any]],
+    overrides: dict[str, Any] | None = None,
+    spec_model: Any | None = None,
+) -> dict[str, Any]:
+    """Keyword arguments for :func:`agentcore.aws.agentcore_harness.invoke_harness`."""
+    overrides = overrides or {}
+    opts: dict[str, Any] = {
+        "region": region,
+        "harness_arn": harness_arn,
+        "runtime_session_id": session_id,
+        "messages": messages,
+    }
+    if overrides.get("model"):
+        opts["model"] = overrides["model"]
+    elif spec_model is not None:
+        opts["model"] = build_model_override(spec_model)
+    if overrides.get("systemPrompt"):
+        opts["system_prompt"] = [{"text": overrides["systemPrompt"]}]
+    if overrides.get("skills"):
+        opts["skills"] = overrides["skills"]
+    if overrides.get("actorId"):
+        opts["actor_id"] = overrides["actorId"]
+    max_iterations = overrides.get("maxIterations")
+    opts["max_iterations"] = max_iterations if max_iterations is not None else DEFAULT_MAX_ITERATIONS
+    if overrides.get("maxTokens") is not None:
+        opts["max_tokens"] = overrides["maxTokens"]
+    if overrides.get("timeoutSeconds") is not None:
+        opts["timeout_seconds"] = overrides["timeoutSeconds"]
+    if overrides.get("allowedTools"):
+        opts["allowed_tools"] = overrides["allowedTools"]
+    if overrides.get("tools"):
+        opts["tools"] = overrides["tools"]
+    return opts