runlayer 0.31.2__tar.gz → 0.31.3__tar.gz

{runlayer-0.31.2 → runlayer-0.31.3}/AGENTS.md

@@ -342,6 +342,7 @@ uv run runlayer run test_uuid --secret test_key --host http://localhost:8000
 
 - Never log API keys or tokens
 - Validate all inputs
+- `runlayer run` stdio children get a minimal environment (`main.py:_build_stdio_env`): the backend-configured `env` plus a short proxy/TLS/locale allowlist, on top of mcp's platform base set. Never pass `os.environ` through — the AI client's env carries cloud credentials.
 - Use HTTPS by default
 - Provide clear security guidance in docs
 

{runlayer-0.31.2 → runlayer-0.31.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: runlayer
-Version: 0.31.2
+Version: 0.31.3
 Summary: A command-line interface for running MCP servers via HTTP transport
 Project-URL: Homepage, https://runlayer.com
 Project-URL: Documentation, https://docs.runlayer.com/

{runlayer-0.31.2 → runlayer-0.31.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "runlayer"
-version = "0.31.2"
+version = "0.31.3"
 description = "A command-line interface for running MCP servers via HTTP transport"
 readme = "README.md"
 requires-python = ">=3.10"

{runlayer-0.31.2 → runlayer-0.31.3}/runlayer_cli/commands/aiwatch_config.py

@@ -48,12 +48,33 @@ def _config_callback(ctx: typer.Context) -> None:
         raise typer.Exit()
 
 
+_UNRECOGNIZED_SECRET = "set (unrecognized format)"
+
+
+def _redact_secret(field: str, value: str) -> str:
+    # Recognized keys render the way the dashboard shows that key type, so an
+    # operator can match a device to a key by eye (pinned by
+    # tests/fixtures/managed_secret_display_cases.json). Anything else is
+    # masked outright: `config show` output gets pasted into tickets, and a
+    # wrong-type or truncated value must not echo more than the old
+    # `****<last4>` did.
+    if field == "enrollment_key":
+        if value.startswith("rl_enroll_") and len(value) > 14:
+            return f"{value[:10]}...{value[-4:]}"
+        return _UNRECOGNIZED_SECRET
+    if value.startswith("rl_org_") and len(value) > 14:
+        return f"{value[:14]}..."
+    return _UNRECOGNIZED_SECRET
+
+
 def _redact_config(config: mdm_config.ManagedConfig) -> dict[str, object]:
     redacted: dict[str, object] = {}
     for key, value in config.items():
         if key in mdm_config.SECRET_FIELDS:
             redacted[key] = (
-                f"****{value[-4:]}" if isinstance(value, str) and value else "not set"
+                _redact_secret(key, value)
+                if isinstance(value, str) and value
+                else "not set"
             )
         else:
             redacted[key] = value

{runlayer-0.31.2 → runlayer-0.31.3}/runlayer_cli/commands/scan.py

@@ -737,6 +737,47 @@ def _run_scan(
                 fg=typer.colors.YELLOW,
             )
 
+        if submission.manifest_regressed:
+            scopes = ", ".join(
+                scope for scope, _last_accepted_at in submission.manifest_regressed
+            )
+            # ISO-8601 UTC strings from one backend sort lexicographically.
+            last_accepted_at = max(
+                accepted_at for _scope, accepted_at in submission.manifest_regressed
+            )
+            typer.secho(
+                f"{WARN} Scan manifest rejected: {scopes} predate the last "
+                f"accepted scan (started {last_accepted_at})",
+                fg=typer.colors.YELLOW,
+            )
+
+        if submission.manifest_superseded and not quiet:
+            scopes = ", ".join(
+                scope for scope, _last_accepted_at in submission.manifest_superseded
+            )
+            last_accepted_at = max(
+                accepted_at for _scope, accepted_at in submission.manifest_superseded
+            )
+            typer.echo(
+                f"Manifest superseded by a newer scan (started {last_accepted_at}) "
+                f"for {scopes}"
+            )
+
+        if submission.positives_superseded and not quiet:
+            identifiers = [
+                identifier for _kind, identifier in submission.positives_superseded
+            ]
+            shown = ", ".join(identifiers[:5])
+            if len(identifiers) > 5:
+                shown += f", +{len(identifiers) - 5} more"
+            count = len(identifiers)
+            noun = "finding" if count == 1 else "findings"
+            typer.secho(
+                f"{WARN} {count} device-scoped {noun} superseded by a newer scan "
+                f"on this device and not recorded: {shown}",
+                fg=typer.colors.YELLOW,
+            )
+
         # The WARN lines above already told the user what happened; here we only
         # act on the exit-code policy the orchestrator computed.
         exit_code = submission.exit_code

{runlayer-0.31.2 → runlayer-0.31.3}/runlayer_cli/commands/setup.py

@@ -490,7 +490,7 @@ _CODEX_HOOK_MATCHERS = {
     "PostToolUse": "",
     "PostToolUseFailure": "",
     "PermissionRequest": "Bash",
-    "SessionStart": "startup|resume",
+    "SessionStart": "startup|resume|clear|compact",
 }
 
 _HERMES_ENFORCEMENT_HOOKS = [

{runlayer-0.31.2 → runlayer-0.31.3}/runlayer_cli/error_classification.py

@@ -29,6 +29,8 @@ from collections.abc import Iterator
 
 import httpx
 
+from runlayer_cli.flow_contract import status_category
+
 if sys.version_info >= (3, 11):
     import builtins
 
@@ -92,20 +94,6 @@ def iter_exception_tree(
         queue.extend(link for link in links if id(link) not in seen)
 
 
-def _status_category(status_code: int) -> str:
-    if status_code == 401:
-        return "http_401"
-    if status_code == 403:
-        return "http_403"
-    if status_code == 404:
-        return "http_404"
-    if 400 <= status_code < 500:
-        return "http_4xx"
-    if 500 <= status_code < 600:
-        return "http_5xx"
-    return "other"
-
-
 def _classify_single(exc: BaseException) -> tuple[str, int | None]:
     """Classify exactly one exception object (no chain or group walking)."""
     # OAuth first: these subclass generic errors (OAuthCallbackTimeoutError is
@@ -121,7 +109,7 @@ def _classify_single(exc: BaseException) -> tuple[str, int | None]:
             return ("other", None)
         if 400 <= status_code < 500:
             return ("oauth_registration_rejected", status_code)
-        return (_status_category(status_code), status_code)
+        return (status_category(status_code), status_code)
     if isinstance(exc, OAuthCallbackTimeoutError):
         return ("oauth_flow_timeout", None)
     # Device-local listener failures (occupied cached port, loopback policy)
@@ -138,7 +126,7 @@ def _classify_single(exc: BaseException) -> tuple[str, int | None]:
 
     if isinstance(exc, httpx.HTTPStatusError):
         status_code = exc.response.status_code
-        return (_status_category(status_code), status_code)
+        return (status_category(status_code), status_code)
 
     if isinstance(exc, httpx.ConnectTimeout):
         return ("connect_timeout", None)

{runlayer-0.31.2 → runlayer-0.31.3}/runlayer_cli/flow_contract.py

@@ -144,6 +144,25 @@ CLIENT_FLOW_HOOK_EVENTS: frozenset[str] = frozenset(
 )
 
 
+def status_category(status_code: int) -> str:
+    """Map an HTTP status to its ``CLIENT_FLOW_ERROR_CATEGORIES`` member. Lives
+    here (stdlib-only, already inside the hook import closure) rather than in
+    ``error_classification`` so the relay's non-2xx path does not drag the MCP
+    client stack into the packaged hook."""
+    category = "other"
+    if status_code == 401:
+        category = "http_401"
+    elif status_code == 403:
+        category = "http_403"
+    elif status_code == 404:
+        category = "http_404"
+    elif 400 <= status_code < 500:
+        category = "http_4xx"
+    elif 500 <= status_code < 600:
+        category = "http_5xx"
+    return category
+
+
 def build_envelope(flows: list[dict[str, Any]], dropped: int) -> dict[str, Any]:
     """Wire envelope attached to existing request bodies as ``client_flows``.
 

{runlayer-0.31.2 → runlayer-0.31.3}/runlayer_cli/hook/clients.py

@@ -124,7 +124,7 @@ def normalize_event_name(event: str) -> str:
 _POST_TOOL_EVENTS = frozenset({"PostToolUse", "PostToolUseFailure"})
 
 # Session events whose hook output may add model-visible context.
-_CONTEXT_EVENTS = frozenset({"SessionStart", "UserPromptSubmit"})
+_CONTEXT_EVENTS = frozenset({"SessionStart"})
 _CONTEXT_CLIENTS = frozenset({Client.CLAUDE_CODE, Client.CODEX})
 
 # Cline parses stdout by scanning for lines prefixed ``HOOK_CONTROL\t`` (last one
@@ -762,7 +762,7 @@ class HookResponse:
         """Allow a session event and add model-visible context.
 
         Claude Code and Codex share the ``hookSpecificOutput.additionalContext``
-        contract on session start and prompt submit.
+        contract on session start.
         """
         if self._client in _CONTEXT_CLIENTS and self._event in _CONTEXT_EVENTS:
             return json.dumps(

{runlayer-0.31.2 → runlayer-0.31.3}/runlayer_cli/hook/dispatch.py

@@ -9,7 +9,7 @@ import time
 from collections.abc import Callable
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Any, NoReturn, cast
+from typing import Any, NoReturn, cast, Literal
 
 from runlayer_cli import __version__, flow_spool, flow_trace, regex_safe
 from runlayer_cli.hook import credential_state, hook_io, host_override, messages
@@ -52,6 +52,7 @@ from runlayer_cli.hook.mcp_lookup import (
     resolve_hermes_mcp_tool,
 )
 from runlayer_cli.hook.failure import FailureContext
+from runlayer_cli.flow_contract import status_category
 from runlayer_cli.hook.relay import (
     RelayError,
     check_tool_lifecycle,
@@ -173,18 +174,52 @@ def _policy_violation(check: Callable[[], None]) -> FilePolicyViolation | None:
     return None
 
 
-def _credential_deny_kwargs(failure: FailureContext | None) -> dict[str, Any]:
-    """Hostname + credential kind for the 401 deny only; empty otherwise."""
+def _device_deny_kwargs(failure: FailureContext | None) -> dict[str, Any]:
+    """Device context for denies that name the device: hostname + credential
+    kind for Runlayer's 401, hostname alone for a network rejection (the block
+    is per device, so IT needs the hostname; no credential was judged)."""
+    kwargs: dict[str, Any] = {}
+    if failure is not None and failure.kind == "http":
+        if failure.is_network_rejection:
+            kwargs = {"hostname": device_hostname()}
+        elif failure.status_code == credential_state.CREDENTIAL_REJECTED_STATUS:
+            kwargs = {
+                "hostname": device_hostname(),
+                "managed_credential": uses_managed_credential(),
+            }
+    return kwargs
+
+
+_InfraDenyErrorType = Literal["HookNetworkDeny", "HookInfraDeny"]
+
+
+def _mark_infra_deny(failure: FailureContext | None, *, override: bool) -> None:
+    """Mark the flow for a fail-closed relay deny. This is where the flow
+    learns the HTTP category of a deny. The relay marks only Runlayer's own
+    401 (the credential verdict, see ``relay._note_credential_rejection``);
+    every other non-2xx is left unmarked there because some are recovered
+    (gzip identity retry) or swallowed by best-effort callers and must not
+    count as failed flows in the hook-reliability alerts."""
+    kwargs: dict[str, Any] = {}
     if (
-        failure is None
-        or failure.kind != "http"
-        or failure.status_code != credential_state.CREDENTIAL_REJECTED_STATUS
+        failure is not None
+        and failure.kind == "http"
+        and failure.status_code is not None
     ):
-        return {}
-    return {
-        "hostname": device_hostname(),
-        "managed_credential": uses_managed_credential(),
-    }
+        kwargs = {
+            "category": status_category(failure.status_code),
+            "http_status": failure.status_code,
+        }
+    flow_trace.mark_error(_infra_deny_error_type(failure), override=override, **kwargs)
+
+
+def _infra_deny_error_type(failure: FailureContext | None) -> _InfraDenyErrorType:
+    """Flow error type for a fail-closed relay deny: ``HookNetworkDeny`` when
+    an intermediary rejected the request (nothing reached Runlayer), else
+    ``HookInfraDeny``. Log-only labels (see the hook-reliability alert rules),
+    so per-customer triage can split "our 4xx" from "their edge 4xx"."""
+    is_network = failure is not None and failure.is_network_rejection
+    return "HookNetworkDeny" if is_network else "HookInfraDeny"
 
 
 # Flow error type for "Monitor device, credentials rejected, call allowed".
@@ -790,11 +825,11 @@ def _check_tool_lifecycle(
             flow_trace.mark_error("HookAuthRequired", override=True)
             u, a = messages.tool_auth_required(tool_name=tool_name)
         else:
-            flow_trace.mark_error("HookInfraDeny", override=True)
+            _mark_infra_deny(e.failure, override=True)
             u, a = messages.tool_api_unreachable(
                 tool_name=tool_name,
                 failure=e.failure,
-                **_credential_deny_kwargs(e.failure),
+                **_device_deny_kwargs(e.failure),
             )
         if target == "tool-post":
             _write(
@@ -1149,15 +1184,12 @@ _PLUGIN_CONTEXT_CLIENTS = frozenset({Client.CLAUDE_CODE, Client.CODEX})
 
 
 def _plugin_context_output(ctx: _DispatchCtx) -> str | None:
-    """Session/prompt output carrying Runlayer Plugin routing rules.
+    """Session-start output carrying Runlayer Plugin routing rules.
 
-    None when the client or event has no context slot, or the built-in plugin
-    is not configured for this session, so callers fall back to plain allow.
+    None when the client has no context slot, or the built-in plugin is not
+    configured for this session, so the caller falls back to plain output.
     """
-    if ctx.client not in _PLUGIN_CONTEXT_CLIENTS or ctx.hook_type not in (
-        "SessionStart",
-        "UserPromptSubmit",
-    ):
+    if ctx.client not in _PLUGIN_CONTEXT_CLIENTS:
         return None
     cwd = ctx.input_data.get("cwd", "") or hook_io.getcwd()
     context = build_plugin_context(ctx.client, cwd)
@@ -1182,7 +1214,7 @@ def _handle_session_event(ctx: _DispatchCtx) -> None:
     forward_event(
         ctx.client.value, ctx.original_hook_type, ctx.input_data, debug=ctx.debug
     )
-    _write(_plugin_context_output(ctx) or ctx.resp.allow())
+    _write(ctx.resp.allow())
 
 
 def _handle_post_tool_use(ctx: _DispatchCtx) -> None:
@@ -1557,7 +1589,7 @@ def _mcp_enforce_and_respond(
         elif mode is AIWatchMode.PROTECT:
             flow_trace.mark_error("HookInfraFailOpen")
         else:
-            flow_trace.mark_error("HookInfraDeny")
+            _mark_infra_deny(e.failure, override=False)
         if mode is AIWatchMode.PROTECT:
             return _allow_protect_failure()
         if e.exit_code == 1:
@@ -1566,7 +1598,7 @@ def _mcp_enforce_and_respond(
             u, a = messages.api_unreachable(
                 tool_name=tool_name,
                 failure=e.failure,
-                **_credential_deny_kwargs(e.failure),
+                **_device_deny_kwargs(e.failure),
             )
         _deny_and_exit(resp, u, a)
 

runlayer-0.31.3/runlayer_cli/hook/failure.py

@@ -0,0 +1,205 @@
+"""Relay failure classification shared by the relay and deny-message rendering.
+
+Extracted from ``hook/relay.py`` (ENG-5365) so ``messages.py`` can import the
+context type at runtime without pulling the whole relay module. Keep this
+module stdlib + httpx only.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any, Literal, NamedTuple
+
+import httpx
+
+# Closed vocabulary for FailureContext.kind. messages._unreachable_cause has a
+# rendering branch per kind (contract-tested); a kind added here without one
+# falls back to the generic legacy message.
+FailureKind = Literal["connect", "upload_timeout", "upload_failed", "timeout", "http"]
+
+# Who answered a non-2xx. ``"runlayer"``: the Runlayer application (its error
+# responses carry ``X-Runlayer-Origin`` and ``X-Request-ID`` and a JSON
+# ``{"detail": ...}`` body). ``"intermediary"``: something in front of it — an
+# AWS WAF IP-allowlist block, an ALB error page, a corporate proxy — which
+# returns the same status codes with an HTML body and neither header. The
+# distinction decides both wording (a WAF 403 is a network rejection, not a
+# Runlayer policy decision) and whether a 401 may touch the credential caches
+# (an intermediary 401 says nothing about the Runlayer credential).
+ResponseOrigin = Literal["runlayer", "intermediary"]
+
+# Header names the backend stamps on every error response it answers. The
+# origin header's value is a fixed literal; only its presence is inspected.
+ORIGIN_HEADER_NAME = "X-Runlayer-Origin"
+REQUEST_ID_HEADER_NAME = "X-Request-ID"
+
+# Statuses an intermediary can answer that would otherwise read as a Runlayer
+# credential (401) or policy (403) decision. Other intermediary statuses (an
+# ALB 5xx with no healthy target, a proxy 429) keep the generic
+# answered-request wording, which blames the request, not Runlayer.
+NETWORK_REJECT_STATUSES = frozenset({401, 403})
+
+# Server-supplied text is rendered into the deny reason, so it is bounded and
+# reduced to printable characters; a request id is only echoed when it looks
+# like one.
+_MAX_DETAIL_CHARS = 200
+_MAX_REQUEST_ID_CHARS = 64
+_REQUEST_ID_CHARS = frozenset(
+    "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789._:-"
+)
+
+
+@dataclass(frozen=True, slots=True)
+class FailureContext:
+    """What a failed relay POST knew at the moment it failed (ENG-5197).
+
+    ``kind``: ``"connect"`` (no connection acquired — includes pool
+    exhaustion), ``"upload_timeout"`` (body still uploading when the write
+    timed out), ``"upload_failed"`` (connection dropped while the body was
+    uploading), ``"timeout"`` (request sent, no response in time), ``"http"``
+    (non-2xx, see ``status_code``), or ``None`` (unclassified). ``payload_bytes``
+    is the UTF-8 wire size of the request body; ``elapsed_s`` is time spent in
+    the POST before it failed (all attempts, retries included);
+    ``attempts`` is how many attempts ran before giving up (1 = no retry).
+    Carried whole on ``RelayError`` so new fields never need re-threading
+    through call sites.
+    """
+
+    kind: FailureKind | None = None
+    payload_bytes: int | None = None
+    elapsed_s: float | None = None
+    status_code: int | None = None
+    attempts: int = 1
+    # ``kind == "http"`` only. ``None`` = unclassified (a transport without
+    # headers, or callers that predate classification): status-only wording,
+    # treated as Runlayer.
+    origin: ResponseOrigin | None = None
+    # Echoed only for a Runlayer-origin response, so support can find the
+    # server-side log line. Already shape-checked and bounded.
+    request_id: str | None = None
+    # The backend's ``detail`` string, sanitized and bounded; never set for an
+    # intermediary (its body is untrusted HTML and is not rendered).
+    detail: str | None = None
+
+    @property
+    def is_network_rejection(self) -> bool:
+        """An HTTP 401/403 attributed to an intermediary: worded as a network
+        rejection, and no credential state may be touched."""
+        return (
+            self.kind == "http"
+            and self.origin == "intermediary"
+            and self.status_code in NETWORK_REJECT_STATUSES
+        )
+
+
+class ResponseOriginInfo(NamedTuple):
+    origin: ResponseOrigin | None
+    request_id: str | None
+    detail: str | None
+
+
+_UNCLASSIFIED = ResponseOriginInfo(None, None, None)
+_INTERMEDIARY = ResponseOriginInfo("intermediary", None, None)
+
+
+def _sanitize_detail(value: Any) -> str | None:
+    if not isinstance(value, str):
+        return None
+    printable = "".join(c if c.isprintable() else " " for c in value)
+    cleaned = " ".join(printable.split())
+    if len(cleaned) > _MAX_DETAIL_CHARS:
+        cleaned = cleaned[: _MAX_DETAIL_CHARS - 1].rstrip() + "…"
+    return cleaned or None
+
+
+def _request_id(headers: Any) -> str | None:
+    value = headers.get(REQUEST_ID_HEADER_NAME)
+    if not isinstance(value, str):
+        return None
+    value = value.strip()
+    is_token = (
+        0 < len(value) <= _MAX_REQUEST_ID_CHARS and set(value) <= _REQUEST_ID_CHARS
+    )
+    return value if is_token else None
+
+
+def _error_envelope(text: Any) -> dict[str, Any] | None:
+    """The backend's ``{"detail": ...}`` body, or ``None`` for anything else
+    (HTML, non-object JSON, unparseable). ``detail`` may be a list (422); the
+    envelope shape is what proves the origin, the caller decides what to
+    render. ``json.loads`` can raise more than ``ValueError`` on hostile input
+    (``RecursionError`` on deep nesting), so anything it raises means "not an
+    envelope"."""
+    if not isinstance(text, str) or not text:
+        return None
+    try:
+        body = json.loads(text)
+    except Exception:
+        return None
+    return body if isinstance(body, dict) and "detail" in body else None
+
+
+def classify_response_origin(resp: Any) -> ResponseOriginInfo:
+    """Decide who produced a non-2xx response.
+
+    Runlayer when the origin header is present, or — for backends predating
+    it — when the response carries a request id *and* the JSON error envelope
+    (both come from the same handler, so either alone is not enough: proxies
+    add request-id headers of their own, and any hop can answer JSON).
+    Anything else with headers is an intermediary; a response object without
+    headers at all is unclassified. Never raises: classification is garnish
+    on a deny that must still be emitted, so any failure inside it also
+    yields "unclassified" (the pre-classification behaviour).
+    """
+    headers = getattr(resp, "headers", None)
+    if headers is None:
+        return _UNCLASSIFIED
+    try:
+        request_id = _request_id(headers)
+        envelope = _error_envelope(getattr(resp, "text", None))
+        marked = headers.get(ORIGIN_HEADER_NAME) is not None
+    except Exception:
+        return _UNCLASSIFIED
+    if marked or (request_id is not None and envelope is not None):
+        detail = _sanitize_detail(envelope.get("detail")) if envelope else None
+        return ResponseOriginInfo("runlayer", request_id, detail)
+    return _INTERMEDIARY
+
+
+def _safe_wire_size(payload: str | bytes) -> int | None:
+    """Byte size of the body as sent (UTF-8, post-compression when compressed),
+    or ``None`` if the encode itself fails.
+
+    A compressed body is already bytes, so sizing it is O(1). The str encode
+    allocates a full copy of a potentially multi-MB body; under memory
+    pressure it can raise. Size is diagnostic garnish — it must never be the
+    reason a deny path stops denying (fail-closed depends on ``RelayError``
+    actually being raised).
+    """
+    try:
+        if isinstance(payload, bytes):
+            return len(payload)
+        return len(payload.encode("utf-8"))
+    except Exception:
+        return None
+
+
+def _classify_network_failure(exc: Exception) -> FailureKind | None:
+    """Map an httpx transport exception to a ``FailureContext.kind``.
+
+    ``WriteTimeout``/``WriteError`` both prove the body was still in flight
+    (timed out vs connection dropped — the latter is the signature of the
+    stalled uploads the ALB reaps). ``PoolTimeout`` means no connection was
+    ever acquired (shared-client saturation), so it is "connect", not
+    "timeout": only read timeouts mean the request was sent with no response
+    in time. Non-httpx exceptions stay unclassified rather than guessing.
+    """
+    if isinstance(exc, httpx.WriteTimeout):
+        return "upload_timeout"
+    if isinstance(exc, httpx.WriteError):
+        return "upload_failed"
+    if isinstance(exc, httpx.ConnectError | httpx.ConnectTimeout | httpx.PoolTimeout):
+        return "connect"
+    if isinstance(exc, httpx.TimeoutException):
+        return "timeout"
+    return None