agentcore-cli 0.31.1__py3-none-any.whl

agentcore/operations/dev/invoke.py

@@ -0,0 +1,214 @@
+"""Port of operations/dev/invoke.ts: invoke the local HTTP agent (/invocations)."""
+
+import codecs
+import json
+import re
+import traceback
+from collections.abc import Iterator
+from typing import Any
+
+from agentcore.lib.errors.types import DevServerConnectionError, DevServerError
+from agentcore.operations.dev._http import fetch
+from agentcore.operations.dev.invoke_types import InvokeStreamingOptions, SSELogger, log_to
+from agentcore.operations.dev.utils import is_connection_error, sleep
+
+MAX_RETRIES = 5
+BASE_DELAY_MS = 500
+_LINE_SPLIT = re.compile(r"\r?\n")
+
+
+def _js_string(value: Any) -> str:
+    if isinstance(value, str):
+        return value
+    if value is None:
+        return "null"
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (dict, list)):
+        return "[object Object]" if isinstance(value, dict) else ",".join(_js_string(v) for v in value)
+    return str(value)
+
+
+def parse_sse_line(line: str) -> tuple[str | None, str | None]:
+    """``(content, error)`` carried by one SSE ``data:`` line."""
+    if not line.startswith("data: "):
+        return None, None
+    raw = line[6:]
+    try:
+        parsed = json.loads(raw)
+    except ValueError:
+        return raw, None
+    if isinstance(parsed, str):
+        return parsed, None
+    if isinstance(parsed, dict):
+        if "error" in parsed:
+            return None, _js_string(parsed["error"])
+        if "text" in parsed:
+            return _js_string(parsed["text"]), None
+        event = parsed.get("event")
+        if isinstance(event, dict):
+            text = ((event.get("contentBlockDelta") or {}).get("delta") or {}).get("text")
+            if isinstance(text, str):
+                return text, None
+    return None, None
+
+
+def parse_sse(text: str) -> str:
+    parts: list[str] = []
+    for line in text.split("\n"):
+        content, error = parse_sse_line(line)
+        if error:
+            return f"Error: {error}"
+        if content:
+            parts.append(content)
+    return "".join(parts) if parts else text
+
+
+def extract_result(text: str) -> str:
+    try:
+        parsed = json.loads(text)
+    except ValueError:
+        return text
+    if isinstance(parsed, dict) and "result" in parsed:
+        result = parsed["result"]
+        return result if isinstance(result, str) else json.dumps(result, indent=2, ensure_ascii=False)
+    return json.dumps(parsed, indent=2, ensure_ascii=False)
+
+
+def _request_headers(custom: dict[str, str] | None) -> dict[str, str]:
+    return {
+        "Content-Type": "application/json",
+        "Accept": "text/event-stream",
+        "x-amzn-bedrock-agentcore-runtime-session-id": "local-dev-session",
+        **(custom or {}),
+    }
+
+
+def _stack(err: BaseException) -> str:
+    return "".join(traceback.format_exception(err)).rstrip() if err.__traceback__ else str(err)
+
+
+def _retry_loop_error(err: BaseException, attempt: int, logger: SSELogger | None) -> bool:
+    """Shared catch block: True to retry; raises for HTTP and non-connection errors."""
+    if isinstance(err, DevServerError):
+        log_to(logger, "error", f"Server error ({err.status_code}): {err}")
+        raise err
+    if is_connection_error(err):
+        delay = BASE_DELAY_MS * 2**attempt
+        log_to(
+            logger,
+            "warn",
+            f"Connection failed (attempt {attempt + 1}/{MAX_RETRIES}): {err}. Retrying in {delay}ms...",
+        )
+        sleep(delay)
+        return True
+    log_to(logger, "error", f"Request failed: {_stack(err)}")
+    raise err
+
+
+def _final_error(last: BaseException | None, logger: SSELogger | None, default: str) -> DevServerConnectionError:
+    final = DevServerConnectionError(str(last) if last else default)
+    final.__cause__ = last
+    log_to(logger, "error", f"Failed to connect after {MAX_RETRIES} attempts: {final}")
+    return final
+
+
+def invoke_agent_streaming(options: InvokeStreamingOptions | int, message: str | None = None) -> Iterator[str]:
+    """Stream text chunks from the local agent's SSE response (falls back to plain JSON bodies)."""
+    if isinstance(options, int):
+        options = InvokeStreamingOptions(port=options, message=message or "")
+    port, logger = options.port, options.logger
+    last: BaseException | None = None
+
+    for attempt in range(MAX_RETRIES):
+        try:
+            res = fetch(
+                f"http://localhost:{port}/invocations",
+                method="POST",
+                headers=_request_headers(options.headers),
+                body=json.dumps({"prompt": options.message}),
+            )
+            if not res.ok:
+                raise DevServerError(res.status, res.text())
+
+            decoder = codecs.getincrementaldecoder("utf-8")(errors="replace")
+            buffer = ""
+            full = ""
+            yielded = False
+            for chunk in res.iter_chunks():
+                decoded = decoder.decode(chunk)
+                buffer += decoded
+                full += decoded
+                lines = _LINE_SPLIT.split(buffer)
+                buffer = lines.pop()
+                for line in lines:
+                    if logger is not None and line.strip():
+                        logger.log_sse_event(line)
+                    content, error = parse_sse_line(line)
+                    if error:
+                        yield f"Error: {error}"
+                        return
+                    if content:
+                        yield content
+                        yielded = True
+            if buffer:
+                if logger is not None and buffer.strip():
+                    logger.log_sse_event(buffer)
+                content, error = parse_sse_line(buffer)
+                if error:
+                    yield f"Error: {error}"
+                    return
+                if content:
+                    yield content
+                    yielded = True
+            if not yielded and full.strip():
+                yield extract_result(full.strip())
+            return
+        except Exception as err:  # noqa: BLE001 - classified below, as upstream
+            last = err
+            _retry_loop_error(err, attempt, logger)
+    raise _final_error(last, logger, "Failed to connect to dev server after retries")
+
+
+def invoke_for_protocol(protocol: str, options: InvokeStreamingOptions) -> Iterator[str]:
+    """Dispatch to the protocol-specific streaming invoke (MCP uses list/call tools instead)."""
+    if protocol == "MCP":
+        raise RuntimeError("Use listMcpTools/callMcpTool for MCP agents")
+    if protocol == "A2A":
+        from agentcore.operations.dev.invoke_a2a import invoke_a2a_streaming
+
+        yield from invoke_a2a_streaming(options)
+    elif protocol == "AGUI":
+        from agentcore.operations.dev.invoke_agui import invoke_agui_streaming
+
+        yield from invoke_agui_streaming(options)
+    else:
+        yield from invoke_agent_streaming(options)
+
+
+def invoke_agent(options: InvokeStreamingOptions | int, message: str | None = None) -> str:
+    """Non-streaming invoke: returns the combined SSE text or the extracted JSON result."""
+    if isinstance(options, int):
+        options = InvokeStreamingOptions(port=options, message=message or "")
+    port, logger = options.port, options.logger
+    last: BaseException | None = None
+    for attempt in range(MAX_RETRIES):
+        try:
+            res = fetch(
+                f"http://localhost:{port}/invocations",
+                method="POST",
+                headers=_request_headers(options.headers),
+                body=json.dumps({"prompt": options.message}),
+            )
+            if not res.ok:
+                raise DevServerError(res.status, res.text())
+            text = res.text()
+            if not text:
+                return "(empty response)"
+            if "data: " in text:
+                return parse_sse(text)
+            return extract_result(text)
+        except Exception as err:  # noqa: BLE001 - classified below, as upstream
+            last = err
+            _retry_loop_error(err, attempt, logger)
+    raise _final_error(last, logger, "Failed to connect to dev server after retries")

agentcore/operations/dev/invoke_a2a.py

@@ -0,0 +1,204 @@
+"""Port of operations/dev/invoke-a2a.ts: local A2A JSON-RPC invoke + agent card."""
+
+import codecs
+import itertools
+import json
+import uuid
+from collections.abc import Callable, Iterator
+from typing import Any
+
+from agentcore.lib.errors.types import DevServerConnectionError, DevServerError
+from agentcore.operations.dev._http import LocalResponse, fetch
+from agentcore.operations.dev.invoke import BASE_DELAY_MS, MAX_RETRIES, _final_error, _retry_loop_error
+from agentcore.operations.dev.invoke_types import InvokeStreamingOptions, SSELogger, log_to
+from agentcore.operations.dev.utils import is_connection_error, sleep
+
+_request_ids = itertools.count(1)
+
+A2AAgentCard = dict[str, Any]
+
+
+def fetch_a2a_agent_card(port: int, logger: SSELogger | None = None) -> A2AAgentCard | None:
+    """Fetch /.well-known/agent-card.json, falling back to the v0.3 /.well-known/agent.json."""
+    for attempt in range(MAX_RETRIES):
+        try:
+            for path in ("/.well-known/agent-card.json", "/.well-known/agent.json"):
+                res = fetch(f"http://localhost:{port}{path}", headers={"Accept": "application/json"})
+                if not res.ok:
+                    res.close()
+                    if res.status == 404 and path == "/.well-known/agent-card.json":
+                        continue
+                    log_to(logger, "warn", f"Agent card not available ({res.status})")
+                    return None
+                card = res.json()
+                log_to(logger, "system", f"A2A agent card: {(card or {}).get('name') or 'unnamed'}")
+                return card
+        except Exception as err:  # noqa: BLE001 - retried or reported, as upstream
+            if is_connection_error(err) and attempt < MAX_RETRIES - 1:
+                sleep(BASE_DELAY_MS * 2**attempt)
+                continue
+            log_to(logger, "warn", f"Failed to fetch agent card: {err}")
+            return None
+    return None
+
+
+def _target(event: dict[str, Any]) -> dict[str, Any]:
+    result = event.get("result")
+    return result if isinstance(result, dict) else event
+
+
+def is_status_update_event(event: dict[str, Any]) -> bool:
+    return _target(event).get("kind") == "status-update"
+
+
+def _parts_text(parts: Any) -> str | None:
+    if not parts:
+        return None
+    texts = [
+        p["text"]
+        for p in parts
+        if isinstance(p, dict) and (p.get("kind") == "text" or p.get("type") == "text") and p.get("text")
+    ]
+    return "".join(texts) if texts else None
+
+
+def extract_task_text(result: dict[str, Any]) -> str | None:
+    """Text from a full Task result (artifacts first, then status message)."""
+    artifacts = result.get("artifacts")
+    if artifacts:
+        texts = [t for a in artifacts if (t := _parts_text((a or {}).get("parts")))]
+        if texts:
+            return "\n".join(texts)
+    message = ((result.get("status") or {}) if isinstance(result.get("status"), dict) else {}).get("message")
+    if isinstance(message, dict) and message.get("parts"):
+        return _parts_text(message["parts"])
+    return None
+
+
+def extract_sse_event_text(event: dict[str, Any], streamed_from_status: bool = False) -> str | None:
+    """Displayable text of an A2A SSE event (artifact-update text is skipped once status streamed it)."""
+    target = _target(event)
+    kind = target.get("kind")
+    if kind == "artifact-update":
+        if streamed_from_status:
+            return None
+        return _parts_text((target.get("artifact") or {}).get("parts"))
+    if kind == "status-update":
+        message = (target.get("status") or {}).get("message")
+        if isinstance(message, dict) and message.get("parts"):
+            return _parts_text(message["parts"])
+        return None
+    return extract_task_text(target)
+
+
+def _handle_sse_event(event: dict[str, Any], on_status: Callable[[str], None] | None) -> None:
+    if on_status is None:
+        return
+    target = _target(event)
+    if target.get("kind") != "status-update":
+        return
+    state = (target.get("status") or {}).get("state")
+    if state:
+        on_status(state)
+
+
+def _parse_a2a_sse_stream(
+    res: LocalResponse, logger: SSELogger | None, on_status: Callable[[str], None] | None
+) -> Iterator[str]:
+    decoder = codecs.getincrementaldecoder("utf-8")(errors="replace")
+    buffer = ""
+    streamed_from_status = False
+    for chunk in res.iter_chunks():
+        buffer += decoder.decode(chunk)
+        lines = buffer.split("\n")
+        buffer = lines.pop()
+        for line in lines:
+            if not line.startswith("data: "):
+                continue
+            data = line[6:].strip()
+            if not data:
+                continue
+            if logger is not None:
+                logger.log_sse_event(line)
+            try:
+                event = json.loads(data)
+                if not isinstance(event, dict):
+                    raise ValueError("not an object")
+                _handle_sse_event(event, on_status)
+                text = extract_sse_event_text(event, streamed_from_status)
+            except (ValueError, AttributeError, TypeError):
+                yield data
+                continue
+            if text:
+                if is_status_update_event(event):
+                    streamed_from_status = True
+                yield text
+
+
+def invoke_a2a_streaming(options: InvokeStreamingOptions) -> Iterator[str]:
+    """JSON-RPC ``message/stream`` (SSE) with a non-streaming JSON fallback."""
+    port, logger = options.port, options.logger
+    last: BaseException | None = None
+    for attempt in range(MAX_RETRIES):
+        try:
+            body = {
+                "jsonrpc": "2.0",
+                "id": next(_request_ids),
+                "method": "message/stream",
+                "params": {
+                    "message": {
+                        "messageId": str(uuid.uuid4()),
+                        "role": "user",
+                        "parts": [{"kind": "text", "text": options.message}],
+                    }
+                },
+            }
+            log_to(logger, "system", f"A2A message/stream: {options.message}")
+            res = fetch(
+                f"http://localhost:{port}/",
+                method="POST",
+                headers={"Content-Type": "application/json", "Accept": "text/event-stream", **(options.headers or {})},
+                body=json.dumps(body),
+            )
+            if not res.ok:
+                raise DevServerError(res.status, res.text())
+
+            if "text/event-stream" in (res.header("content-type") or ""):
+                yield from _parse_a2a_sse_stream(res, logger, options.on_status)
+                return
+
+            text = res.text()
+            if logger is not None:
+                logger.log_sse_event(text)
+            try:
+                parsed = json.loads(text)
+                if not isinstance(parsed, dict):
+                    raise ValueError("not an object")
+            except ValueError:
+                yield text
+                return
+            if parsed.get("error"):
+                rpc_error = parsed["error"] if isinstance(parsed["error"], dict) else {}
+                raise DevServerError(rpc_error.get("code") or 500, rpc_error.get("message") or "A2A RPC error")
+            result = parsed.get("result")
+            if result:
+                task_text = extract_task_text(result) if isinstance(result, dict) else None
+                yield task_text or json.dumps(result, indent=2, ensure_ascii=False)
+            else:
+                yield text
+            return
+        except Exception as err:  # noqa: BLE001 - classified by the shared retry handler
+            last = err
+            _retry_loop_error(err, attempt, logger)
+    raise _final_error(last, logger, "Failed to connect to A2A server after retries")
+
+
+__all__ = [
+    "A2AAgentCard",
+    "DevServerConnectionError",
+    "extract_sse_event_text",
+    "extract_task_text",
+    "fetch_a2a_agent_card",
+    "invoke_a2a_streaming",
+    "is_status_update_event",
+]

agentcore/operations/dev/invoke_agui.py

@@ -0,0 +1,88 @@
+"""Port of operations/dev/invoke-agui.ts: local AG-UI invoke (RunAgentInput over SSE)."""
+
+import json
+import uuid
+from collections.abc import Iterator
+
+from agentcore.aws.agui_parser import parse_agui_sse_stream
+from agentcore.aws.agui_types import AguiEventType
+from agentcore.lib.errors.types import DevServerError
+from agentcore.operations.dev._http import fetch
+from agentcore.operations.dev.invoke import MAX_RETRIES, _final_error, _retry_loop_error
+from agentcore.operations.dev.invoke_types import InvokeStreamingOptions, log_to
+
+
+def invoke_agui_streaming(options: InvokeStreamingOptions) -> Iterator[str]:
+    port, logger = options.port, options.logger
+    last: BaseException | None = None
+    streaming = False
+
+    for attempt in range(MAX_RETRIES):
+        try:
+            body = {
+                "threadId": options.thread_id or str(uuid.uuid4()),
+                "runId": str(uuid.uuid4()),
+                "messages": [{"id": str(uuid.uuid4()), "role": "user", "content": options.message}],
+                "tools": [],
+                "context": [],
+                "state": {},
+                "forwardedProps": {},
+            }
+            log_to(logger, "system", f"AGUI invoke: {options.message}")
+            res = fetch(
+                f"http://localhost:{port}/invocations",
+                method="POST",
+                headers={"Content-Type": "application/json", "Accept": "text/event-stream", **(options.headers or {})},
+                body=json.dumps(body),
+            )
+            if not res.ok:
+                raise DevServerError(res.status, res.text())
+
+            streams = parse_agui_sse_stream(res.iter_chunks(), logger=logger, single_consumer=True)
+            yielded = False
+            tool_calls: list[dict[str, str]] = []
+            active_id = active_name = active_args = ""
+
+            for event in streams.event_stream:
+                etype = event.get("type")
+                if etype in (AguiEventType.TEXT_MESSAGE_CONTENT, AguiEventType.TEXT_MESSAGE_CHUNK):
+                    delta = event.get("delta")
+                    if delta:
+                        streaming = True
+                        yield delta
+                        yielded = True
+                elif etype == AguiEventType.TOOL_CALL_START:
+                    active_id = event.get("toolCallId") or ""
+                    active_name = event.get("toolCallName") or ""
+                    active_args = ""
+                elif etype == AguiEventType.TOOL_CALL_ARGS:
+                    if event.get("delta"):
+                        active_args += event["delta"]
+                elif etype == AguiEventType.TOOL_CALL_END:
+                    if active_name:
+                        tool_calls.append({"id": active_id, "name": active_name, "args": active_args})
+                    active_id = active_name = active_args = ""
+                elif etype == AguiEventType.TOOL_CALL_RESULT:
+                    content = event.get("content")
+                    matching = next((tc for tc in tool_calls if tc["id"] == (event.get("toolCallId") or "")), None)
+                    if matching and content:
+                        rendered = content if isinstance(content, str) else json.dumps(content, separators=(",", ":"))
+                        matching["args"] = f"{matching['args']} → {rendered}"
+                elif etype == AguiEventType.RUN_ERROR:
+                    message = event.get("message") if "message" in event else "Unknown AGUI error"
+                    yield f"Error: {message}"
+                    return
+
+            if not yielded and tool_calls:
+                for tc in tool_calls:
+                    yield f"[Tool: {tc['name']}({tc['args']})]\n"
+                yielded = True
+            if not yielded:
+                yield "(no content in AGUI response)"
+            return
+        except Exception as err:
+            last = err
+            if streaming:
+                raise
+            _retry_loop_error(err, attempt, logger)
+    raise _final_error(last, logger, "Failed to connect to AGUI server after retries")

agentcore/operations/dev/invoke_mcp.py

@@ -0,0 +1,145 @@
+"""Port of operations/dev/invoke-mcp.ts: list/call tools on a local MCP server."""
+
+import itertools
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+from agentcore.lib.errors.types import DevServerError
+from agentcore.lib.utils.json_rpc import parse_json_rpc_response
+from agentcore.operations.dev._http import fetch
+from agentcore.operations.dev.invoke import MAX_RETRIES, _final_error, _retry_loop_error
+from agentcore.operations.dev.invoke_types import SSELogger, log_to
+
+_request_ids = itertools.count(1)
+
+McpTool = dict[str, Any]
+
+
+@dataclass
+class McpToolsResult:
+    tools: list[McpTool] = field(default_factory=list)
+    session_id: str | None = None
+
+
+def _post(port: int, headers: dict[str, str], body: dict[str, Any]):  # type: ignore[no-untyped-def]
+    return fetch(f"http://localhost:{port}/mcp", method="POST", headers=headers, body=json.dumps(body))
+
+
+def list_mcp_tools(
+    port: int, logger: SSELogger | None = None, custom_headers: dict[str, str] | None = None
+) -> McpToolsResult:
+    """initialize + notifications/initialized + tools/list; returns tools and the MCP session id."""
+    last: BaseException | None = None
+    for attempt in range(MAX_RETRIES):
+        try:
+            init_body = {
+                "jsonrpc": "2.0",
+                "id": next(_request_ids),
+                "method": "initialize",
+                "params": {
+                    "protocolVersion": "2025-03-26",
+                    "capabilities": {},
+                    "clientInfo": {"name": "agentcore-cli", "version": "1.0.0"},
+                },
+            }
+            log_to(logger, "system", "MCP initialize")
+            init_res = _post(
+                port,
+                {
+                    "Content-Type": "application/json",
+                    "Accept": "application/json, text/event-stream",
+                    **(custom_headers or {}),
+                },
+                init_body,
+            )
+            if not init_res.ok:
+                raise DevServerError(init_res.status, init_res.text())
+            session_id = init_res.header("mcp-session-id")
+            init_text = init_res.text()
+            if logger is not None:
+                logger.log_sse_event(init_text)
+
+            session_headers = {"Content-Type": "application/json", **(custom_headers or {})}
+            if session_id:
+                session_headers["mcp-session-id"] = session_id
+            _post(port, session_headers, {"jsonrpc": "2.0", "method": "notifications/initialized"}).close()
+
+            log_to(logger, "system", "MCP tools/list")
+            list_res = _post(
+                port,
+                {
+                    "Content-Type": "application/json",
+                    "Accept": "application/json, text/event-stream",
+                    **session_headers,
+                },
+                {"jsonrpc": "2.0", "id": next(_request_ids), "method": "tools/list", "params": {}},
+            )
+            if not list_res.ok:
+                raise DevServerError(list_res.status, list_res.text())
+            list_text = list_res.text()
+            if logger is not None:
+                logger.log_sse_event(list_text)
+            parsed = parse_json_rpc_response(list_text)
+            tools = ((parsed.get("result") or {}) if isinstance(parsed.get("result"), dict) else {}).get("tools") or []
+            return McpToolsResult(
+                tools=[
+                    {
+                        k: v
+                        for k, v in {
+                            "name": t.get("name"),
+                            "description": t.get("description"),
+                            "inputSchema": t.get("inputSchema"),
+                        }.items()
+                        if v is not None
+                    }
+                    for t in tools
+                ],
+                session_id=session_id or None,
+            )
+        except Exception as err:  # noqa: BLE001 - classified by the shared retry handler
+            last = err
+            _retry_loop_error(err, attempt, logger)
+    raise _final_error(last, logger, "Failed to connect to MCP server after retries")
+
+
+def call_mcp_tool(
+    port: int,
+    tool_name: str,
+    args: dict[str, Any],
+    session_id: str | None = None,
+    logger: SSELogger | None = None,
+    custom_headers: dict[str, str] | None = None,
+) -> str:
+    """tools/call; returns the concatenated text content (or the pretty-printed result)."""
+    body = {
+        "jsonrpc": "2.0",
+        "id": next(_request_ids),
+        "method": "tools/call",
+        "params": {"name": tool_name, "arguments": args},
+    }
+    log_to(logger, "system", f"MCP tools/call: {tool_name}({json.dumps(args, separators=(',', ':'))})")
+    headers = {
+        "Content-Type": "application/json",
+        "Accept": "application/json, text/event-stream",
+        **(custom_headers or {}),
+    }
+    if session_id:
+        headers["mcp-session-id"] = session_id
+    res = _post(port, headers, body)
+    if not res.ok:
+        raise DevServerError(res.status, res.text())
+    text = res.text()
+    if logger is not None:
+        logger.log_sse_event(text)
+    parsed = parse_json_rpc_response(text)
+    if parsed.get("error"):
+        rpc_error = parsed["error"] if isinstance(parsed["error"], dict) else {}
+        raise RuntimeError(rpc_error.get("message") or f"MCP error (code {rpc_error.get('code')})")
+    result = parsed.get("result")
+    content = result.get("content") if isinstance(result, dict) else None
+    if content:
+        texts = [item["text"] for item in content if isinstance(item, dict) and "text" in item]
+        if texts:
+            return "".join(texts)
+    return json.dumps(result, indent=2, ensure_ascii=False)

agentcore/operations/dev/invoke_types.py

@@ -0,0 +1,30 @@
+"""Port of operations/dev/invoke-types.ts."""
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Protocol
+
+
+class SSELogger(Protocol):
+    """Logger for SSE events; ``log(level, message)`` is optional (checked with getattr)."""
+
+    def log_sse_event(self, raw_line: str) -> None: ...
+
+
+@dataclass
+class InvokeStreamingOptions:
+    port: int
+    message: str
+    logger: SSELogger | None = None
+    on_status: Callable[[str], None] | None = None
+    """A2A task status updates (e.g. 'working', 'input-required')."""
+    headers: dict[str, str] | None = None
+    thread_id: str | None = None
+    """Persistent AGUI thread ID for multi-turn conversations."""
+
+
+def log_to(logger: object | None, level: str, message: str) -> None:
+    """Call ``logger.log(level, message)`` when the logger has one (``logger?.log?.(...)``)."""
+    log = getattr(logger, "log", None) if logger is not None else None
+    if callable(log):
+        log(level, message)