agent-engine-runner-shared 0.11.9__tar.gz → 0.11.10__tar.gz

{agent_engine_runner_shared-0.11.9 → agent_engine_runner_shared-0.11.10}/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+- Reuse a process-wide keep-alive mTLS client for OE callbacks (tool
+  execute/result, node events, progress and custom events) and drain callback
+  response bodies so connections return to the pool; removes a full TLS
+  handshake per callback.
+
 ### Fixed
 - Uncaught exceptions in agent code now emit one filterable `level=ERROR`
   record instead of only `WARNING`. Ordinary stderr writes with no

{agent_engine_runner_shared-0.11.9 → agent_engine_runner_shared-0.11.10}/Dockerfile

@@ -5,7 +5,7 @@
 # Usage: docker buildx build -t runner:latest -f packages/python/packages/agent-engine-runner-shared/Dockerfile .
 
 ARG BASE_TARGETPLATFORM=linux/amd64
-ARG RUNNER_BASE_IMAGE=664315256653.dkr.ecr.us-east-1.amazonaws.com/base/amazonlinux2023-python:v3.11-202512082043-f9f77a3
+ARG RUNNER_BASE_IMAGE=664315256653.dkr.ecr.us-east-1.amazonaws.com/base/amazonlinux2023-python:v3.11-202610191636-2ff39c3@sha256:30ecac067fceafe43a5f0f5e80d1725b60708204dcd2fe3f176363417e2a2402
 
 FROM --platform=${BASE_TARGETPLATFORM} ghcr.io/astral-sh/uv@sha256:ff07b86af50d4d9391d9daf4ff89ce427bc544f9aae87057e69a1cc0aa369946 AS uv
 

{agent_engine_runner_shared-0.11.9 → agent_engine_runner_shared-0.11.10}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.5
 Name: agent-engine-runner-shared
-Version: 0.11.9
+Version: 0.11.10
 Summary: Runner SDK - Framework-agnostic agent runtime
 License: Apache-2.0
 License-File: LICENSE
 Requires-Python: >=3.11
-Requires-Dist: agent-engine-sdk-memory==0.11.9
-Requires-Dist: agent-engine-sdk==0.11.9
+Requires-Dist: agent-engine-sdk-memory==0.11.10
+Requires-Dist: agent-engine-sdk==0.11.10
 Requires-Dist: fastapi>=0.141.1
 Requires-Dist: filelock>=3.0.0
 Requires-Dist: httpx-sse>=0.4.0
@@ -21,7 +21,7 @@ Requires-Dist: pyyaml>=6.0
 Requires-Dist: regex>=2026.4.4
 Requires-Dist: sentry-sdk>=2.27.0
 Requires-Dist: starlette>=1.7.0
-Requires-Dist: uvicorn>=0.32.0
+Requires-Dist: uvicorn>=0.50.0
 Provides-Extra: debug
 Requires-Dist: debugpy>=1.8.0; extra == 'debug'
 Provides-Extra: dev

{agent_engine_runner_shared-0.11.9 → agent_engine_runner_shared-0.11.10}/docs/api.md

@@ -174,10 +174,14 @@
     * [response\_from\_stream\_chunks](#agent_engine_runner_shared.secure_llm_proxy.SecureLLMProxy.response_from_stream_chunks)
     * [stream](#agent_engine_runner_shared.secure_llm_proxy.SecureLLMProxy.stream)
 * [agent\_engine\_runner\_shared.secure\_wrapper](#agent_engine_runner_shared.secure_wrapper)
+  * [\_OAuthAuthorizationRequired](#agent_engine_runner_shared.secure_wrapper._OAuthAuthorizationRequired)
+    * [\_\_init\_\_](#agent_engine_runner_shared.secure_wrapper._OAuthAuthorizationRequired.__init__)
+  * [oauth\_authorization\_wait\_id](#agent_engine_runner_shared.secure_wrapper.oauth_authorization_wait_id)
   * [extract\_usage](#agent_engine_runner_shared.secure_wrapper.extract_usage)
   * [PolicyDeniedException](#agent_engine_runner_shared.secure_wrapper.PolicyDeniedException)
   * [OERetryAfterError](#agent_engine_runner_shared.secure_wrapper.OERetryAfterError)
   * [ToolExecutionError](#agent_engine_runner_shared.secure_wrapper.ToolExecutionError)
+  * [ToolPlatformError](#agent_engine_runner_shared.secure_wrapper.ToolPlatformError)
   * [TerminalExecutionError](#agent_engine_runner_shared.secure_wrapper.TerminalExecutionError)
   * [raise\_for\_oe\_rejection](#agent_engine_runner_shared.secure_wrapper.raise_for_oe_rejection)
   * [ToolCallTimeoutError](#agent_engine_runner_shared.secure_wrapper.ToolCallTimeoutError)
@@ -2733,6 +2737,36 @@ This module provides:
 
 HITL is handled via LangGraph's native interrupt() / Command(resume=...) API.
 
+<a id="agent_engine_runner_shared.secure_wrapper._OAuthAuthorizationRequired"></a>
+
+## \_OAuthAuthorizationRequired
+
+```python
+class _OAuthAuthorizationRequired(Exception)
+```
+
+Leave durable dispatch with typed consent control instead of interrupting its activity.
+
+<a id="agent_engine_runner_shared.secure_wrapper._OAuthAuthorizationRequired.__init__"></a>
+
+#### \_\_init\_\_
+
+```python
+def __init__(elicitation: ElicitationInfo, step: int) -> None
+```
+
+Carry the OE response to its activity boundary without exposing it in errors.
+
+<a id="agent_engine_runner_shared.secure_wrapper.oauth_authorization_wait_id"></a>
+
+#### oauth\_authorization\_wait\_id
+
+```python
+def oauth_authorization_wait_id(value: Any) -> str | None
+```
+
+Identify a consent wait only when this attempt recorded the platform's challenge.
+
 <a id="agent_engine_runner_shared.secure_wrapper.extract_usage"></a>
 
 #### extract\_usage
@@ -2783,12 +2817,26 @@ class ToolExecutionError(Exception)
 
 Raised when tool execution fails.
 
+<a id="agent_engine_runner_shared.secure_wrapper.ToolPlatformError"></a>
+
+## ToolPlatformError
+
+```python
+class ToolPlatformError(ToolExecutionError)
+```
+
+Raised when the platform, not the tool, failed a tool call.
+
+The tool may already have run, for example when OE rejects or never
+acknowledges its result, so an adapter must not report this to the model as
+a failed tool it could call again.
+
 <a id="agent_engine_runner_shared.secure_wrapper.TerminalExecutionError"></a>
 
 ## TerminalExecutionError
 
 ```python
-class TerminalExecutionError(ToolExecutionError)
+class TerminalExecutionError(ToolPlatformError)
 ```
 
 Raised when OE rejects a tool call because the execution already ended.
@@ -3077,24 +3125,30 @@ Clean up resources owned by this execution's wrapper.
 #### execute\_tool
 
 ```python
-def execute_tool(tool_name: str,
-                 arguments: Dict[str, Any],
-                 *,
-                 metadata: Optional[Dict[str, Any]] = None,
-                 provider_type: Optional[str] = None,
-                 scopes: Optional[list[str]] = None,
-                 tool_call_id: Optional[str] = None,
-                 raw_on_interrupt: bool = False,
-                 redact_fields: Optional[list[str]] = None,
-                 is_local: bool = True,
-                 local_executor: Optional[Callable[[], Any]] = None,
-                 is_framework_control_flow: Optional[Callable[[BaseException],
-                                                              bool]] = None,
-                 call_channel_expected: bool = False) -> Any
+def execute_tool(
+        tool_name: str,
+        arguments: Dict[str, Any],
+        *,
+        metadata: Optional[Dict[str, Any]] = None,
+        provider_type: Optional[str] = None,
+        scopes: Optional[list[str]] = None,
+        tool_call_id: Optional[str] = None,
+        raw_on_interrupt: bool = False,
+        redact_fields: Optional[list[str]] = None,
+        is_local: bool = True,
+        local_executor: Optional[Callable[[], Any]] = None,
+        is_framework_control_flow: Optional[Callable[[BaseException],
+                                                     bool]] = None,
+        call_channel_expected: bool = False,
+        on_unknown_outcome: Optional[UnknownOutcomePolicy] = None) -> Any
 ```
 
 Execute a tool call through OE.
 
+Durable OAuth records a typed challenge before a separate framework
+wait, then records the actual resource call after reauthorization.
+Its consent answer never becomes a tool result or Memory content.
+
 **Arguments**:
 
 - `tool_name` - Name of the tool
@@ -3111,6 +3165,9 @@ Execute a tool call through OE.
 - `is_local` - Whether OE should return the approved call to this AER.
 - `local_executor` - Callback that invokes the registered tool on the
   current framework stack. Required for local tools.
+- `on_unknown_outcome` - What a retry does when the runner was lost while
+  this tool was in flight in a durable workflow: ``"rerun"`` runs it
+  again, ``"fail"`` refuses the retry.
 
 
 **Returns**:
@@ -3132,20 +3189,22 @@ Execute a tool call through OE.
 
 ```python
 def create_secure_tool_function(
-    original_tool: Any,
-    tool_name: str,
-    *,
-    allow_direct: bool = False,
-    metadata: Optional[Dict[str, Any]] = None,
-    is_local: bool = True,
-    provider_type: Optional[str] = None,
-    scopes: Optional[list[str]] = None,
-    response_format: Literal["content", "content_and_artifact"] = "content",
-    tool_declared_format: Optional[Literal["content",
-                                           "content_and_artifact"]] = None,
-    redact_fields: Optional[list[str]] = None,
-    is_framework_control_flow: Optional[Callable[[BaseException], bool]] = None
-) -> Callable
+        original_tool: Any,
+        tool_name: str,
+        *,
+        allow_direct: bool = False,
+        metadata: Optional[Dict[str, Any]] = None,
+        is_local: bool = True,
+        provider_type: Optional[str] = None,
+        scopes: Optional[list[str]] = None,
+        response_format: Literal["content",
+                                 "content_and_artifact"] = "content",
+        tool_declared_format: Optional[Literal["content",
+                                               "content_and_artifact"]] = None,
+        redact_fields: Optional[list[str]] = None,
+        is_framework_control_flow: Optional[Callable[[BaseException],
+                                                     bool]] = None,
+        on_unknown_outcome: Optional[UnknownOutcomePolicy] = None) -> Callable
 ```
 
 Create a wrapped tool function that routes through SecureToolWrapper.
@@ -3165,6 +3224,9 @@ to be built before execution context exists.
 - `tool_declared_format` - The tool author's own original format, used only
   to decide whether a normal result gets shape-matched into a tuple.
   Defaults to ``response_format``.
+- `on_unknown_outcome` - What a retry does when the runner was lost while
+  this tool was in flight in a durable workflow: ``"rerun"`` runs it
+  again, ``"fail"`` refuses the retry.
 
 
 **Returns**:

{agent_engine_runner_shared-0.11.9 → agent_engine_runner_shared-0.11.10}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-engine-runner-shared"
-version = "0.11.9"
+version = "0.11.10"
 description = "Runner SDK - Framework-agnostic agent runtime"
 readme = "README.md"
 license = {text = "Apache-2.0"}
@@ -12,7 +12,9 @@ dependencies = [
     # validation, which can disagree with scope["path"]. The
     # Host-validating _HOST_RE landed in starlette 1.4.1.
     "starlette>=1.7.0",
-    "uvicorn>=0.32.0",
+    # The launcher relies on uvicorn's STARTUP_FAILURE (exit 3) contract for
+    # lifespan startup and bind failures, added in 0.50.0.
+    "uvicorn>=0.50.0",
     "pydantic>=2.0.0",
     "protobuf>=6.33.6,<7",
     "httpx>=0.27.0",
@@ -23,9 +25,9 @@ dependencies = [
     "jsonschema>=4.26.0",
     "sentry-sdk>=2.27.0",
     # BaseAgent protocol and AgentInput/AgentEvent models
-    "agent-engine-sdk==0.11.9",
+    "agent-engine-sdk==0.11.10",
     # Memory models and the MemoryClient HTTP client
-    "agent-engine-sdk-memory==0.11.9",
+    "agent-engine-sdk-memory==0.11.10",
     # Required for checkpoint message decoding (query/sessions endpoints)
     "msgpack>=1.0.0",
     # Required by guardrails_evaluator/regex.py for advanced regex matching

{agent_engine_runner_shared-0.11.9 → agent_engine_runner_shared-0.11.10}/src/agent_engine_runner_shared/__init__.py

@@ -96,6 +96,7 @@ from agent_engine_runner_shared.secure_wrapper import (
     TerminalExecutionError,
     ToolCallTimeoutError,
     ToolExecutionError,
+    ToolPlatformError,
     extract_usage,
 )
 from agent_engine_runner_shared.structured_logging import (
@@ -190,6 +191,7 @@ __all__ = [
     "TerminalExecutionError",
     "ToolCallTimeoutError",
     "ToolExecutionError",
+    "ToolPlatformError",
     "ExternalAPICallError",
     # Utilities
     "extract_usage",

agent_engine_runner_shared-0.11.10/src/agent_engine_runner_shared/caller_trace.py

@@ -0,0 +1,138 @@
+"""Distinguish an inbound caller trace from a root this runner created.
+
+AER always starts ``aer.execute``. With no inbound traceparent that span is a
+root, and ``tls_client`` injects it on the call to the OE. The OE forwards
+that header, so the tool process sees a remote parent even though no caller
+trace was bound. W3C traceparent cannot say who created the root, so the
+outgoing tracestate carries ``agentengine=root`` for a runner-created trace.
+Guardrail content is recorded only when that marker is absent.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import Any, Iterator
+
+# Simple W3C tracestate member. A value of "root" means a runner process
+# created this trace; an inbound caller does not set it.
+RUNNER_ROOT_TRACESTATE_KEY = "agentengine"
+RUNNER_ROOT_TRACESTATE_VALUE = "root"
+
+_RUNNER_ROOTED_KEY: Any = None
+
+
+def _runner_rooted_key() -> Any:
+    global _RUNNER_ROOTED_KEY
+    if _RUNNER_ROOTED_KEY is None:
+        from opentelemetry import context
+
+        _RUNNER_ROOTED_KEY = context.create_key("agentengine.runner_rooted_trace")
+    return _RUNNER_ROOTED_KEY
+
+
+def trace_state_marks_runner_root(trace_state: Any) -> bool:
+    """True when tracestate says a runner created this trace's root."""
+    if trace_state is None:
+        return False
+    try:
+        marked = RUNNER_ROOT_TRACESTATE_KEY in trace_state
+    except TypeError:
+        return False
+    if not marked:
+        return False
+    return trace_state[RUNNER_ROOT_TRACESTATE_KEY] == RUNNER_ROOT_TRACESTATE_VALUE
+
+
+def merge_runner_root_trace_state(existing: str | None) -> str:
+    """Return tracestate with the runner-root member first, without duplicates."""
+    kept: list[str] = []
+    prefix = f"{RUNNER_ROOT_TRACESTATE_KEY}="
+    for part in (existing or "").split(","):
+        item = part.strip()
+        if not item or item.startswith(prefix):
+            continue
+        kept.append(item)
+    member = f"{RUNNER_ROOT_TRACESTATE_KEY}={RUNNER_ROOT_TRACESTATE_VALUE}"
+    return ",".join([member, *kept])
+
+
+def parent_context_is_runner_rooted(parent_context: Any) -> bool:
+    """True when ``parent_context`` is not an inbound caller trace.
+
+    An invalid extract means this process is about to create the root. A
+    remote parent without the runner-root marker was already bound by a caller.
+    """
+    from opentelemetry import trace
+
+    span_context = trace.get_current_span(parent_context).get_span_context()
+    if span_context is None or not span_context.is_valid:
+        return True
+    if trace_state_marks_runner_root(getattr(span_context, "trace_state", None)):
+        return True
+    if getattr(span_context, "is_remote", False):
+        return False
+    return True
+
+
+def bind_runner_rooted_trace(ctx: Any, rooted: bool) -> Any:
+    """Return ``ctx`` with the runner-rooted flag set for descendant spans."""
+    from opentelemetry import context
+
+    return context.set_value(_runner_rooted_key(), rooted, ctx)
+
+
+def runner_rooted_trace_active() -> bool:
+    """True when the active span's trace was created by a runner, not a caller.
+
+    The flag set at span entry wins. Without it, a remote parent that carries
+    the marker — or any local root — is treated as runner-created so guardrail
+    content stays off unless a caller trace was already bound.
+    """
+    try:
+        from opentelemetry import context, trace
+    except ImportError:
+        return False
+
+    explicit = context.get_value(_runner_rooted_key())
+    if explicit is True:
+        return True
+    if explicit is False:
+        return False
+
+    span = trace.get_current_span()
+    span_context = span.get_span_context()
+    if trace_state_marks_runner_root(getattr(span_context, "trace_state", None)):
+        return True
+    parent = getattr(span, "parent", None)
+    if parent is not None and getattr(parent, "is_valid", False):
+        if trace_state_marks_runner_root(getattr(parent, "trace_state", None)):
+            return True
+        if getattr(parent, "is_remote", False):
+            return False
+        # Parent was created in this process and nobody bound a caller trace.
+        return True
+    if span_context is not None and span_context.is_valid:
+        if getattr(span_context, "is_remote", False):
+            return trace_state_marks_runner_root(getattr(span_context, "trace_state", None))
+        return True
+    return False
+
+
+@contextmanager
+def runner_trace_scope(parent_context: Any) -> Iterator[None]:
+    """Attach the runner-rooted flag for the span about to be started.
+
+    ``start_as_current_span`` copies the ambient context, so the flag has to
+    be attached before the span or nested ``tls_client`` calls will not see it.
+    """
+    try:
+        from opentelemetry import context as otel_context
+    except ImportError:
+        yield
+        return
+    rooted = parent_context_is_runner_rooted(parent_context)
+    token = otel_context.attach(bind_runner_rooted_trace(otel_context.get_current(), rooted))
+    try:
+        yield
+    finally:
+        otel_context.detach(token)

{agent_engine_runner_shared-0.11.9 → agent_engine_runner_shared-0.11.10}/src/agent_engine_runner_shared/connectors/README.md

@@ -107,14 +107,17 @@ Only GET, HEAD and OPTIONS retry 429/503, at most three times; `Retry-After` is
 at 30 seconds. Each invocation carries a 30-second budget between requests, redirects,
 response chunks and retry waits. Every request
 uses its remaining budget for HTTPX's standard connect, read, write and pool timeouts;
-the read timeout bounds each blocking read, as defined by HTTPX.
+the read timeout bounds each blocking read, as defined by HTTPX. Requests carry
+`User-Agent: agent-engine-connector` unless the connector sets its own in
+`auth.headers`, matched case-insensitively.
 
 HTTP failures, including rejected provider redirects, use `httpx.HTTPStatusError`,
 and transport failures use the existing
 timeout/connection exception types recognized by `classify_tool_api_error`. An HTTP
 error may retain a bounded provider error body (at most 4 KB) so the shared classifier
-can surface the provider's own explanation. The retained body is never logged; the
-classifier applies rudimentary hygiene to the extracted explanation — control
-characters dropped, URL-shaped text rejected, exact credential values redacted, result
-bounded. This is best-effort, not a guarantee. Oversized bodies, redirect locations,
+can surface the provider's own explanation: a recognized JSON error field, or a
+plain-text body that is not HTML markup, up to its first link. The retained body is
+never logged; the classifier applies rudimentary hygiene to the extracted explanation
+— control characters dropped, URL-shaped text rejected, exact credential values
+redacted, result bounded. This is best-effort, not a guarantee. Oversized bodies, redirect locations,
 and credential-bearing request objects are never retained.

{agent_engine_runner_shared-0.11.9 → agent_engine_runner_shared-0.11.10}/src/agent_engine_runner_shared/connectors/executor.py

@@ -39,6 +39,9 @@ MAX_RETRIES = 3
 # Mirrors the classifier's envelope cap: only a body small enough to be parsed
 # as a provider error envelope is retained on a raised HTTP error.
 MAX_ERROR_ENVELOPE_BYTES = 4096
+# Sent when the connector supplies none: the bare transport skips httpx.Client,
+# which normally adds one, and some providers refuse requests without it.
+USER_AGENT = "agent-engine-connector"
 
 
 def _origin(url: httpx.URL) -> tuple[str, str, int | None]:
@@ -83,9 +86,15 @@ class ConnectorExecutor:
         ):
             raise ValueError("connector path credential must be materialized before execution")
         self._operations = {tool.name: tool for tool in self._definitions.tools}
-        # The transport provides pooling without Client's cookie or redirect state.
+        # The transport provides pooling without Client's cookie or redirect state,
+        # and ignores proxy and netrc settings. Trust still follows SSL_CERT_FILE /
+        # SSL_CERT_DIR so a TLS-inspecting gateway's CA (`agentengine dev up
+        # --ca-bundle`) is honoured; the process environment is tenant-owned, so
+        # this trusts nothing the tenant could not already change in-process.
         self._transport = (
-            transport if transport is not None else httpx.HTTPTransport(trust_env=False)
+            transport
+            if transport is not None
+            else httpx.HTTPTransport(trust_env=False, verify=httpx.create_ssl_context())
         )
         self._timeout_seconds = timeout_seconds
 
@@ -187,6 +196,8 @@ class ConnectorExecutor:
         content, content_type = self._request_body(tool, arguments)
         if content_type:
             headers["Content-Type"] = content_type
+        if not any(name.lower() == "user-agent" for name in headers):
+            headers["User-Agent"] = USER_AGENT
         url = httpx.URL(base_url + path)
         if query:
             url = url.copy_merge_params(query)

{agent_engine_runner_shared-0.11.9 → agent_engine_runner_shared-0.11.10}/src/agent_engine_runner_shared/custom_events.py

@@ -31,8 +31,10 @@ from agent_engine_runner_shared.context import (
     get_current_oe_owner_url,
     report_oe_owner_url_failure,
 )
-from agent_engine_runner_shared.progress import _get_client, _post_chunk_owner_first
+from agent_engine_runner_shared.progress import _post_chunk_owner_first
 from agent_engine_runner_shared.server.chunk_types import CUSTOM_EVENT
+from agent_engine_runner_shared.tls_client import get_shared_client
+from agent_engine_runner_shared.utils import PROGRESS_TIMEOUT_SECS
 
 logger = logging.getLogger(__name__)
 _JSON_OBJECT_ADAPTER = TypeAdapter(dict[str, JsonValue], config=ConfigDict(allow_inf_nan=False))
@@ -154,7 +156,7 @@ class OEHTTPCustomEventTransport:
         if not execution_id or not oe_url:
             return
         try:
-            client = _get_client(oe_url)
+            client = get_shared_client(oe_url)
             _post_chunk_owner_first(
                 client,
                 service_url=f"{oe_url.rstrip('/')}/stream/chunk",
@@ -165,6 +167,7 @@ class OEHTTPCustomEventTransport:
                     "custom_event": dict(payload),
                 },
                 on_owner_failure=report_oe_owner_url_failure,
+                timeout=PROGRESS_TIMEOUT_SECS,
             )
         except Exception as exc:  # noqa: BLE001 - best-effort; never fail the tool
             logger.debug("emit_custom_event: failed to send chunk: %s", exc)

{agent_engine_runner_shared-0.11.9 → agent_engine_runner_shared-0.11.10}/src/agent_engine_runner_shared/error_reporting.py

@@ -41,7 +41,7 @@ _SECRET_INLINE_PATTERN = re.compile(
     r"([\"']?\s*[=:]\s*)"
     r"(\"(?:\\.|[^\"\\])*\"|'(?:\\.|[^'\\])*'|\"(?:\\.|[^\"\\])*$|'(?:\\.|[^'\\])*$|[^\s,]+(?:,(?!\s*[\"']?[A-Za-z0-9_.\-]+[\"']?\s*[=:])[^\s,]+)*)"
 )
-_BEARER_PATTERN = re.compile(r"(?i)\b(bearer)\s+[A-Za-z0-9._\-]+")
+_BEARER_PATTERN = re.compile(r"(?i)\b(bearer)\s+[A-Za-z0-9._\-+/=~]+")
 # Key-name blocklist for structured payloads: a bare secret under a
 # secret-named field matches no inline content pattern, so the field name
 # itself must trigger masking.

{agent_engine_runner_shared-0.11.9 → agent_engine_runner_shared-0.11.10}/src/agent_engine_runner_shared/launcher.py

@@ -38,12 +38,21 @@ from __future__ import annotations
 import importlib
 import logging
 import os
+import re
 import sys
+import threading
 import traceback
 from typing import NoReturn
+from urllib.parse import urlsplit
+from uuid import UUID
 
 from agent_engine_runner_shared.error_reporting import _redact_text
-from agent_engine_runner_shared.mcp_oauth_secret import materialize_mcp_oauth_secret_cache
+from agent_engine_runner_shared.mcp_oauth_secret import (
+    materialize_mcp_oauth_secret_cache,
+    mcp_oauth_secret_values,
+)
+from agent_engine_runner_shared.startup_state import has_startup_completed, reset_startup_state
+from agent_engine_runner_shared.tool_api_error import is_credential_name
 from agent_engine_runner_shared.utils import get_runtime_mode, setup_logging
 
 logger = logging.getLogger(__name__)
@@ -61,6 +70,93 @@ _TERMINATION_LOG_PATH = "/dev/termination-log"
 # since there's no cross-language shared package for this).
 _TERMINATION_MESSAGE_MAX_BYTES = 4 * 1024
 _TERMINATION_MESSAGE_MAX_LINES = 40
+_STARTUP_REPORT_DEADLINE_SECONDS = 2.0
+_STARTUP_REPORT_MAX_BYTES = 512
+_STARTUP_REPORT_INPUT_BYTES = 4096
+_CONTROL_CHARS = re.compile(r"[\x00-\x1f\x7f-\x9f\u2028\u2029]")
+_startup_secrets: tuple[str, ...] = ()
+
+
+def _snapshot_startup_secrets() -> tuple[str, ...]:
+    """Capture credential values before OAuth materialization removes them from the env."""
+    values = {value for name, value in os.environ.items() if value and is_credential_name(name)}
+    values.update(mcp_oauth_secret_values())
+    values.discard("")
+    # Longest first so a secret containing another is replaced whole.
+    return tuple(sorted(values, key=len, reverse=True))
+
+
+def _startup_report_text(text: str) -> str:
+    # Truncating before scrubbing could cut a credential in half and defeat redaction.
+    if len(text.encode("utf-8", errors="replace")) > _STARTUP_REPORT_INPUT_BYTES:
+        return "Startup error message exceeded the reporting limit"
+    # Known values go first: a pattern that redacts only part of a secret would
+    # leave the rest unmatchable by its exact value.
+    for value in _startup_secrets:
+        text = text.replace(value, "<redacted>")
+    text = _redact_text(text)
+    text = _CONTROL_CHARS.sub(" ", text)
+    return text.encode("utf-8")[:_STARTUP_REPORT_MAX_BYTES].decode("utf-8", errors="ignore")
+
+
+def _boot_error_url() -> str | None:
+    raw_boot_id = os.environ.get("AGENTIC_BOOT_ID", "")
+    oe_url = os.environ.get("OE_URL", "")
+    try:
+        boot_id = UUID(raw_boot_id)
+        origin = urlsplit(oe_url)
+        hostname = origin.hostname
+    except ValueError:
+        return None
+    # Match the TypeScript launcher: only the canonical dashed form is a boot ID.
+    if str(boot_id) != raw_boot_id.lower():
+        return None
+    if origin.scheme not in {"http", "https"} or not hostname:
+        return None
+    if origin.username or origin.password:
+        return None
+    return f"{oe_url.rstrip('/')}/boots/{boot_id}/errors"
+
+
+def _report_startup_error(summary: str, exc: BaseException | None, code: int) -> None:
+    """Best-effort POST of a scrubbed startup error to OE; never raises."""
+    try:
+        _send_startup_report(summary, exc, code)
+    except Exception:
+        logger.debug("Startup report could not be prepared")
+
+
+def _send_startup_report(summary: str, exc: BaseException | None, code: int) -> None:
+    """POST a scrubbed startup error to OE, bounded by one deadline."""
+    if has_startup_completed():
+        return
+    url = _boot_error_url()
+    if url is None:
+        logger.debug("Skipping startup report without a valid boot ID and OE URL")
+        return
+    body = {
+        "sandbox": "tool" if _resolve_runner_mode() == "tool" else "agent",
+        "exitCode": code,
+        "errorType": _startup_report_text(type(exc).__name__ if exc else "StartupError"),
+        "message": _startup_report_text(f"{summary}: {exc}" if exc else summary),
+    }
+
+    def send() -> None:
+        from agent_engine_runner_shared.tls_client import create_httpx_client_with_tls
+
+        try:
+            with create_httpx_client_with_tls(url, _STARTUP_REPORT_DEADLINE_SECONDS) as client:
+                # stream() so the response body is never read.
+                with client.stream("POST", url, json=body, follow_redirects=False) as response:
+                    logger.debug("Startup report returned status %d", response.status_code)
+        except Exception:
+            logger.debug("Startup report could not be delivered")
+
+    # httpx timeouts are per phase; a joined daemon thread bounds the whole
+    # exchange (DNS, TLS, headers) and works even when called from an event loop.
+    worker = threading.Thread(target=send, daemon=True)
+    worker.start()
+    worker.join(timeout=_STARTUP_REPORT_DEADLINE_SECONDS)
 
 
 def _bound_text(
@@ -161,6 +257,7 @@ def _fatal(summary: str, exc: BaseException | None = None, code: int = 1) -> NoR
     else:
         logger.error(summary)
     _write_termination_message(summary, exc)
+    _report_startup_error(summary, exc, code)
     sys.exit(code)
 
 
@@ -207,14 +304,17 @@ def _resolve_entrypoint() -> tuple[str, str]:
 
 def main() -> None:
     """Entry point invoked by ``python -m agent_engine_runner_shared.launcher``."""
+    global _startup_secrets
+    reset_startup_state()
+    _startup_secrets = _snapshot_startup_secrets()
     # Install before any import/entrypoint work. After this, print-to-stderr
     # is captured as WARNING (not ERROR), so failure paths must use the logger.
     setup_logging(app_name="launcher", mode=_resolve_runner_mode())
 
     try:
         materialize_mcp_oauth_secret_cache()
-    except (RuntimeError, OSError) as exc:
-        _fatal("Cannot materialize MCP OAuth credentials", exc)
+    except Exception as exc:
+        _fatal("Cannot materialize MCP OAuth credentials", exc, code=EXIT_STARTUP_CRASH)
 
     module_path, target_name = _resolve_entrypoint()