stackgen-sdk 0.4.0rc20__tar.gz → 0.4.0rc22__tar.gz

{stackgen_sdk-0.4.0rc20 → stackgen_sdk-0.4.0rc22}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: stackgen-sdk
-Version: 0.4.0rc20
+Version: 0.4.0rc22
 Summary: StackGen SDK — Aiden, SRE, and Vault from one client
 Project-URL: Homepage, https://appcd-dev.github.io/stackgen-sdk/
 Project-URL: Documentation, https://appcd-dev.github.io/stackgen-sdk/

{stackgen_sdk-0.4.0rc20 → stackgen_sdk-0.4.0rc22}/src/stackgen/_http.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+import os
 import socket
 import ssl
 import time
@@ -34,9 +35,40 @@ def _is_timeout_failure(err: BaseException) -> bool:
     return "timed out" in text
 
 
+DEFAULT_TRANSIENT_RETRY_BUDGET_MS = 120_000
+TRANSIENT_RETRY_MAX_BACKOFF_SECONDS = 15.0
+
+
 def is_retryable_http_status(status: int) -> bool:
-    """GET statuses that self-heal: rate limit and any 5xx (rollout blips, gateway errors)."""
-    return status == 429 or 500 <= status <= 599
+    """Statuses that self-heal: rate limit and any 5xx (rollout blips, gateway errors)."""
+    return status == 429 or status == 499 or 500 <= status <= 599
+
+
+def is_gateway_outage_status(status: int) -> bool:
+    """Gateway / edge outage statuses that get a time-budgeted retry."""
+    return status in (502, 503, 504)
+
+
+def resolve_transient_retry_budget_ms(override: float | int | None = None) -> int:
+    """Resolve the gateway-outage retry budget (ms)."""
+    if override is not None:
+        value = float(override)
+        if value < 0 or value != value:  # NaN check
+            raise ValueError("transient_retry_budget_ms must be a non-negative number")
+        return int(value)
+    raw = os.environ.get("STACKGEN_TRANSIENT_RETRY_BUDGET_MS", "").strip()
+    if raw:
+        try:
+            parsed = float(raw)
+        except ValueError:
+            parsed = -1
+        if parsed >= 0:
+            return int(parsed)
+    return DEFAULT_TRANSIENT_RETRY_BUDGET_MS
+
+
+def is_idempotent_http_method(method: str) -> bool:
+    return method.upper() in {"GET", "HEAD", "PUT", "DELETE"}
 
 
 def is_transient_http_error(err: BaseException) -> bool:
@@ -48,6 +80,15 @@ def is_transient_http_error(err: BaseException) -> bool:
     return is_retryable_http_status(err.status_code)
 
 
+def is_gateway_outage_error(err: BaseException) -> bool:
+    """True for gateway 502/503/504 or statusless transport HttpError."""
+    if not isinstance(err, HttpError):
+        return False
+    if err.status_code is None:
+        return True
+    return is_gateway_outage_status(err.status_code)
+
+
 def http_status_snippet(err: BaseException | None) -> str:
     """Label fragment for TimeoutError / subscribe snippets."""
     if isinstance(err, HttpError) and err.status_code is not None:
@@ -71,8 +112,13 @@ def request(
     expect_json: bool = True,
     retries: int = 3,
     timeout_seconds: float | None = None,
+    transient_retry_budget_ms: float | int | None = None,
 ) -> Any:
-    """Bearer HTTP call with bounded retries on transient GET failures.
+    """Bearer HTTP call with retries on transient failures for idempotent methods.
+
+    Gateway 502/503/504 and network errors retry until
+    ``transient_retry_budget_ms`` elapses (default 120s). Other retryable
+    statuses use the short ``retries`` attempt budget. POST/PATCH fail fast.
 
     ``timeout_seconds`` is an optional per-call abort budget. When the deadline
     expires, raises :class:`~stackgen.errors.TimeoutError`. Omit to wait until
@@ -82,11 +128,33 @@ def request(
         not isinstance(timeout_seconds, (int, float)) or timeout_seconds <= 0
     ):
         raise ValueError("timeout_seconds must be a positive number of seconds")
+    method = method.upper()
+    budget_ms = resolve_transient_retry_budget_ms(transient_retry_budget_ms)
+    idempotent = is_idempotent_http_method(method)
     headers = {"Authorization": f"Bearer {token}"}
     if content_type:
         headers["Content-Type"] = content_type
 
+    started = time.monotonic()
     attempt = 0
+    announced_outage = False
+
+    def within_outage_budget() -> bool:
+        return budget_ms > 0 and (time.monotonic() - started) * 1000 < budget_ms
+
+    def announce_outage(status: object) -> None:
+        nonlocal announced_outage
+        if announced_outage:
+            return
+        announced_outage = True
+        log_http_retry(
+            method,
+            url,
+            status=f"outage:{status}",
+            attempt=attempt,
+            retries=retries,
+        )
+
     while True:
         attempt += 1
         log_http_request(method, url, attempt=attempt)
@@ -107,7 +175,18 @@ def request(
         except urllib.error.HTTPError as err:
             detail = err.read().decode("utf-8", errors="replace")
             log_http_response(method, url, status=err.code, attempt=attempt)
-            if method == "GET" and is_retryable_http_status(err.code) and attempt < retries:
+            if (
+                idempotent
+                and is_gateway_outage_status(err.code)
+                and within_outage_budget()
+            ):
+                announce_outage(err.code)
+                log_http_retry(
+                    method, url, status=err.code, attempt=attempt, retries=retries
+                )
+                time.sleep(min(2**min(attempt, 4), TRANSIENT_RETRY_MAX_BACKOFF_SECONDS))
+                continue
+            if idempotent and is_retryable_http_status(err.code) and attempt < retries:
                 log_http_retry(
                     method, url, status=err.code, attempt=attempt, retries=retries
                 )
@@ -128,7 +207,14 @@ def request(
             if isinstance(err, (socket.timeout, TimeoutError)):
                 raise HttpError(f"{method} {url} -> {err}") from err
             log_http_response(method, url, status=None, attempt=attempt)
-            if method == "GET" and attempt < retries:
+            if idempotent and within_outage_budget():
+                announce_outage("network_error")
+                log_http_retry(
+                    method, url, status="network_error", attempt=attempt, retries=retries
+                )
+                time.sleep(min(2**min(attempt, 4), TRANSIENT_RETRY_MAX_BACKOFF_SECONDS))
+                continue
+            if idempotent and attempt < retries:
                 log_http_retry(
                     method, url, status="network_error", attempt=attempt, retries=retries
                 )

{stackgen_sdk-0.4.0rc20 → stackgen_sdk-0.4.0rc22}/src/stackgen/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.4.0rc20'
-__version_tuple__ = version_tuple = (0, 4, 0, 'rc20')
+__version__ = version = '0.4.0rc22'
+__version_tuple__ = version_tuple = (0, 4, 0, 'rc22')
 
 __commit_id__ = commit_id = None

{stackgen_sdk-0.4.0rc20 → stackgen_sdk-0.4.0rc22}/src/stackgen/aiden/ask.py

@@ -147,6 +147,19 @@ class AskArtifactJourney:
                 "Ask requires additional inputs before execution can start: "
                 f"{inputs_required}"
             )
+        agent = ""
+        for ref in entity_refs or []:
+            if isinstance(ref, dict) and ref.get("type") == "agent":
+                agent = str(ref.get("name") or "")
+                break
+        self._config.emit_session_started(
+            {
+                "kind": "ask",
+                "session_id": data.get("session_id") or data.get("sessionId"),
+                "trace_id": data.get("trace_id") or data.get("traceId"),
+                "agent": agent or None,
+            }
+        )
         return data
 
     def wait_for_execution(self, trace_id: str) -> dict[str, Any]:

{stackgen_sdk-0.4.0rc20 → stackgen_sdk-0.4.0rc22}/src/stackgen/aiden/resources.py

@@ -58,7 +58,11 @@ class AidenResources:
         )
 
     def _get(self, path: str, params: dict[str, Any] | None = None) -> Any:
-        return _http.request(self._url(path, params), self._config.api_token)
+        return _http.request(
+            self._url(path, params),
+            self._config.api_token,
+            transient_retry_budget_ms=self._config.transient_retry_budget_ms,
+        )
 
     def _send(
         self,
@@ -67,7 +71,10 @@ class AidenResources:
         body: Any | None = None,
         params: dict[str, Any] | None = None,
     ) -> Any:
-        kwargs: dict[str, Any] = {"method": method}
+        kwargs: dict[str, Any] = {
+            "method": method,
+            "transient_retry_budget_ms": self._config.transient_retry_budget_ms,
+        }
         if body is not None:
             kwargs["body"] = json.dumps(body).encode("utf-8")
             kwargs["content_type"] = "application/json"
@@ -330,10 +337,19 @@ class AidenResources:
         return _http.as_list(self._get("/tools", params))
 
     def start_agent_chat(self, agent_name: str, body: dict[str, Any]) -> dict[str, Any]:
-        return _as_object(
+        record = _as_object(
             self._send(f"/agents/{agent_name}/chat/start", "POST", body),
             "startAgentChat",
         )
+        self._config.emit_session_started(
+            {
+                "kind": "chat",
+                "session_id": record.get("session_id") or record.get("sessionId"),
+                "trace_id": record.get("trace_id") or record.get("traceId"),
+                "agent": agent_name,
+            }
+        )
+        return record
 
     def list_chat_subscriptions(self, **params: Any) -> list[dict[str, Any]]:
         return _http.as_list(self._get("/platforms/chat/subscriptions", params))
@@ -391,9 +407,18 @@ class AidenResources:
         return _as_object(self._send(f"/workflows/{name}", "DELETE"), "deleteWorkflow")
 
     def run_workflow(self, name: str, body: dict[str, Any] | None = None) -> dict[str, Any]:
-        return _as_object(
+        record = _as_object(
             self._send(f"/workflows/{name}/run", "POST", body or {}), "runWorkflow"
         )
+        self._config.emit_session_started(
+            {
+                "kind": "workflow",
+                "session_id": record.get("session_id") or record.get("sessionId"),
+                "trace_id": record.get("trace_id") or record.get("traceId"),
+                "name": name,
+            }
+        )
+        return record
 
     def create_knowledge_base(self, body: dict[str, Any]) -> dict[str, Any]:
         return _as_object(

{stackgen_sdk-0.4.0rc20 → stackgen_sdk-0.4.0rc22}/src/stackgen/aiden/subscribe.py

@@ -59,16 +59,21 @@ class ExecutionSubscribe:
         chunks: list[str] = []
         reconnects = 0
         last_open_failure = ""
+        outage_budget_ms = int(getattr(self._config, "transient_retry_budget_ms", 0) or 0)
+
+        def can_reconnect(count: int) -> bool:
+            elapsed_ms = (time.monotonic() - started) * 1000
+            return count < SUBSCRIBE_RECONNECT_MAX or (
+                outage_budget_ms > 0 and elapsed_ms < outage_budget_ms
+            )
 
         while remaining_ms() > 100:
             opened = self._open_stream(trace_id, remaining_ms())
             if opened["kind"] == "http":
                 label = transient_status_label(opened["status"])
                 last_open_failure = label
-                if (
-                    not is_transient_status(opened["status"])
-                    or reconnects >= SUBSCRIBE_RECONNECT_MAX
-                ):
+                status = opened["status"]
+                if not is_transient_status(status) or not can_reconnect(reconnects):
                     return self._fail_open(event_count, reconnects, label)
                 reconnects += 1
                 _log.warning(
@@ -83,7 +88,7 @@ class ExecutionSubscribe:
             if opened["kind"] == "network":
                 label = transient_status_label(network=True)
                 last_open_failure = label
-                if reconnects >= SUBSCRIBE_RECONNECT_MAX:
+                if not can_reconnect(reconnects):
                     return self._fail_open(event_count, reconnects, label)
                 reconnects += 1
                 _log.warning(
@@ -114,7 +119,7 @@ class ExecutionSubscribe:
                 raise SdkTimeoutError(
                     "subscribeExecution", int(timeout_ms / 1000)
                 )
-            if pass_result["dropped"] and reconnects < SUBSCRIBE_RECONNECT_MAX:
+            if pass_result["dropped"] and can_reconnect(reconnects):
                 reconnects += 1
                 continue
             break

{stackgen_sdk-0.4.0rc20 → stackgen_sdk-0.4.0rc22}/src/stackgen/aiden/transient.py

@@ -8,6 +8,9 @@ Domain rules (not HTTP mechanics):
 - Only *idempotent* mutations may use :func:`retry_idempotent_op`. Today that
   is ``terminate_session`` (Guild persists cancel intent; empty sessions return
   200). Webhook/workflow starts are *not* idempotent — do not retry them here.
+- Gateway 502/503/504 (and statusless transport errors) keep retrying until
+  the configured outage budget elapses; other transient statuses stay on the
+  short attempt budget so application 500s remain fail-fast.
 """
 
 from __future__ import annotations
@@ -23,7 +26,7 @@ T = TypeVar("T")
 # How many times a subscribe stream may reopen after EOF or a blip fetch.
 SUBSCRIBE_RECONNECT_MAX = 3
 
-# Bounded attempts for an idempotent mutation (terminate).
+# Bounded attempts for an idempotent mutation (terminate) on non-gateway blips.
 IDEMPOTENT_MUTATION_ATTEMPTS = 3
 
 # Backoff base (seconds) between idempotent mutation attempts: 0.5, 1.0, …
@@ -52,22 +55,42 @@ def retry_idempotent_op(
     *,
     attempts: int = IDEMPOTENT_MUTATION_ATTEMPTS,
     backoff_seconds: float = IDEMPOTENT_MUTATION_BACKOFF_SECONDS,
+    budget_ms: float | int | None = None,
     sleep: Callable[[float], None] | None = None,
 ) -> T:
-    """Run an idempotent operation with bounded retries on transient failures.
+    """Run an idempotent operation with retries on transient failures.
 
-    Fail fast on non-transient errors. Callers must only pass ops that are safe
-    to repeat (e.g. terminate_session).
+    Gateway outages (502/503/504 / transport) retry until ``budget_ms`` elapses.
+    Other transient statuses use the short attempt budget. Fail fast on
+    non-transient errors. Callers must only pass ops that are safe to repeat
+    (e.g. terminate_session).
     """
     sleeper = sleep or time.sleep
+    budget = _http.resolve_transient_retry_budget_ms(budget_ms)
+    started = time.monotonic()
     last_err: BaseException | None = None
-    for attempt in range(1, attempts + 1):
+    attempt = 0
+    while True:
+        attempt += 1
         try:
             return op()
         except Exception as err:
             last_err = err
-            if not is_transient_failure(err) or attempt >= attempts:
+            if not is_transient_failure(err):
                 raise
-            sleeper(backoff_seconds * attempt)
+            outage = _http.is_gateway_outage_error(err)
+            within_budget = budget > 0 and (time.monotonic() - started) * 1000 < budget
+            if outage and within_budget:
+                sleeper(
+                    min(
+                        backoff_seconds * attempt,
+                        _http.TRANSIENT_RETRY_MAX_BACKOFF_SECONDS,
+                    )
+                )
+                continue
+            if not outage and attempt < attempts:
+                sleeper(backoff_seconds * attempt)
+                continue
+            raise
     assert last_err is not None
     raise last_err

{stackgen_sdk-0.4.0rc20 → stackgen_sdk-0.4.0rc22}/src/stackgen/aiden/webhook_ops.py

@@ -61,6 +61,13 @@ class WebhookOps:
         )
         if not isinstance(data, dict):
             raise StackgenError(f"unexpected trigger payload: {data!r}")
+        self._config.emit_session_started(
+            {
+                "kind": "webhook",
+                "session_id": data.get("session_id") or data.get("sessionId"),
+                "trace_id": data.get("trace_id") or data.get("traceId"),
+            }
+        )
         return data
 
     def get_webhook_run(self, webhook_id: str, invocation_id: str) -> dict[str, Any]:
@@ -289,7 +296,9 @@ class WebhookOps:
                 raise StackgenError(f"unexpected terminate session payload: {data!r}")
             return data
 
-        return retry_idempotent_op(once)
+        return retry_idempotent_op(
+            once, budget_ms=self._config.transient_retry_budget_ms
+        )
 
     def start_workflow_run(
         self,

{stackgen_sdk-0.4.0rc20 → stackgen_sdk-0.4.0rc22}/src/stackgen/config.py

@@ -2,8 +2,15 @@
 
 from __future__ import annotations
 
+import logging
 import os
-from dataclasses import dataclass
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+from stackgen._http import resolve_transient_retry_budget_ms
+
+_log = logging.getLogger("stackgen")
 
 
 @dataclass(frozen=True)
@@ -16,6 +23,12 @@ class StackgenConfig:
 
     ``log_level`` enables the ``stackgen`` logger (``debug`` / ``info`` /
     ``warn`` / ``error`` / ``silent``). Also set via ``STACKGEN_LOG_LEVEL``.
+
+    ``transient_retry_budget_ms`` rides out gateway 502/503/504 on idempotent
+    calls (default 120s; override with ``STACKGEN_TRANSIENT_RETRY_BUDGET_MS``).
+
+    ``on_session_started`` is called after Ask/chat/workflow/webhook starts
+    with ``kind``, ``session_id``, and ``trace_id`` when present.
     """
 
     base_url: str
@@ -27,6 +40,10 @@ class StackgenConfig:
     output_path: str = "session-report.md"
     poll_interval_seconds: int = 5
     timeout_seconds: int = 1800
+    transient_retry_budget_ms: int = field(
+        default_factory=lambda: resolve_transient_retry_budget_ms()
+    )
+    on_session_started: Callable[[dict[str, Any]], None] | None = None
     log_level: str = ""
 
     def __post_init__(self) -> None:
@@ -36,6 +53,35 @@ class StackgenConfig:
 
             configure_logging(level)
 
+    def emit_session_started(self, info: dict[str, Any]) -> None:
+        """Log and forward a session/trace start."""
+        session_id = str(info.get("session_id") or "").strip()
+        trace_id = str(info.get("trace_id") or "").strip()
+        if not session_id and not trace_id:
+            return
+        kind = str(info.get("kind") or "").strip() or "unknown"
+        agent = str(info.get("agent") or "").strip()
+        name = str(info.get("name") or "").strip()
+        bits = [f"kind={kind}"]
+        if session_id:
+            bits.append(f"session_id={session_id}")
+        if trace_id:
+            bits.append(f"trace_id={trace_id}")
+        if agent:
+            bits.append(f"agent={agent}")
+        if name:
+            bits.append(f"name={name}")
+        _log.info("session started %s", " ".join(bits))
+        if self.on_session_started is not None:
+            payload = {
+                **info,
+                "session_id": session_id or None,
+                "trace_id": trace_id or None,
+                "agent": agent or None,
+                "name": name or None,
+            }
+            self.on_session_started(payload)
+
     def mothership(self) -> str:
         """Normalized mothership URL without trailing slash or ``/guild``."""
         base = self.base_url.rstrip("/")