stackgen-sdk 0.4.0rc8__tar.gz → 0.4.0rc9__tar.gz

{stackgen_sdk-0.4.0rc8 → stackgen_sdk-0.4.0rc9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: stackgen-sdk
-Version: 0.4.0rc8
+Version: 0.4.0rc9
 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.0rc8 → stackgen_sdk-0.4.0rc9}/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.0rc8'
-__version_tuple__ = version_tuple = (0, 4, 0, 'rc8')
+__version__ = version = '0.4.0rc9'
+__version_tuple__ = version_tuple = (0, 4, 0, 'rc9')
 
 __commit_id__ = commit_id = None

{stackgen_sdk-0.4.0rc8 → stackgen_sdk-0.4.0rc9}/src/stackgen/aiden/__init__.py

@@ -6,6 +6,13 @@ from stackgen.aiden.namespace import AidenNamespace
 from stackgen.aiden.resources import PolicyConflictRule
 from stackgen.aiden.run_status import ExecutionStatus, RunPhase, RunStatus
 from stackgen.aiden.steer import is_steer_response
+from stackgen.aiden.transient import (
+    IDEMPOTENT_MUTATION_ATTEMPTS,
+    SUBSCRIBE_RECONNECT_MAX,
+    is_transient_failure,
+    is_transient_status,
+    retry_idempotent_op,
+)
 from stackgen.aiden.webhook import WebhookReportResult
 from stackgen.aiden.workflow_builder import (
     AgentDefinition,
@@ -24,11 +31,13 @@ __all__ = [
     "AskArtifactResult",
     "AuditExportResult",
     "ExecutionStatus",
+    "IDEMPOTENT_MUTATION_ATTEMPTS",
     "PolicyConflictRule",
     "PublishWorkflowResult",
     "RunPhase",
     "RunStatus",
     "StageDefinition",
+    "SUBSCRIBE_RECONNECT_MAX",
     "WebhookReportResult",
     "WorkflowBuilder",
     "WorkflowDefinition",
@@ -36,4 +45,7 @@ __all__ = [
     "create_stage",
     "create_workflow",
     "is_steer_response",
+    "is_transient_failure",
+    "is_transient_status",
+    "retry_idempotent_op",
 ]

stackgen_sdk-0.4.0rc9/src/stackgen/aiden/subscribe.py

@@ -0,0 +1,289 @@
+"""Wait for an execution subscribe stream, then confirm the record settled.
+
+Journey (one caller deadline):
+
+1. Open GET …/executions/{trace_id}/subscribe (SSE).
+2. Read frames until a successful terminal, or the connection drops.
+3. On drop or a transient open failure, reconnect up to
+   :data:`~stackgen.aiden.transient.SUBSCRIBE_RECONNECT_MAX` times.
+4. Confirm via GET …/executions/{trace_id} (retries transient GETs).
+
+Fail-fast: non-retryable 4xx on open; failed/error/cancelled on confirm.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+from stackgen import _http
+from stackgen.aiden.run_status import ExecutionStatus
+from stackgen.aiden.subscribe_frames import consume_subscribe_frames
+from stackgen.aiden.transient import (
+    SUBSCRIBE_RECONNECT_MAX,
+    is_transient_status,
+    transient_status_label,
+)
+
+# Re-export for callers/tests that import from this module.
+__all__ = ["ExecutionSubscribe", "SUBSCRIBE_RECONNECT_MAX", "SubscribeCompleteResult"]
+from stackgen.config import StackgenConfig
+from stackgen.errors import HttpError, TimeoutError as SdkTimeoutError
+
+
+@dataclass
+class SubscribeCompleteResult:
+    ok: bool
+    event_count: int
+    raw_snippet: str
+
+
+class ExecutionSubscribe:
+    def __init__(self, config: StackgenConfig) -> None:
+        self._config = config
+
+    def wait_for_complete(
+        self, trace_id: str, *, timeout_ms: int = 10 * 60 * 1000
+    ) -> SubscribeCompleteResult:
+        started = time.monotonic()
+
+        def remaining_ms() -> int:
+            return timeout_ms - int((time.monotonic() - started) * 1000)
+
+        event_count = 0
+        chunks: list[str] = []
+        reconnects = 0
+        last_open_failure = ""
+
+        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
+                ):
+                    return self._fail_open(event_count, reconnects, label)
+                reconnects += 1
+                time.sleep(min(1.0, max(0.0, remaining_ms() / 1000 - 0.1)))
+                continue
+            if opened["kind"] == "network":
+                label = transient_status_label(network=True)
+                last_open_failure = label
+                if reconnects >= SUBSCRIBE_RECONNECT_MAX:
+                    return self._fail_open(event_count, reconnects, label)
+                reconnects += 1
+                time.sleep(min(1.0, max(0.0, remaining_ms() / 1000 - 0.1)))
+                continue
+            if opened["kind"] == "timeout":
+                raise SdkTimeoutError(
+                    "subscribeExecution", int(timeout_ms / 1000)
+                )
+
+            last_open_failure = ""
+            pass_result = self._read_stream(opened["response"])
+            event_count += pass_result["event_count"]
+            chunks.extend(pass_result["chunks"])
+            if pass_result["completed"]:
+                return self._after_stream_success(
+                    trace_id, event_count, chunks, remaining_ms()
+                )
+            if pass_result["dropped"] and reconnects < SUBSCRIBE_RECONNECT_MAX:
+                reconnects += 1
+                continue
+            break
+
+        return self._fail_stream(event_count, chunks, reconnects, last_open_failure)
+
+    def _subscribe_url(self, trace_id: str) -> str:
+        return (
+            f"{self._config.aiden_url()}/api/v1/executions/{trace_id}/subscribe"
+            + _http.query(self._config.org_id)
+        )
+
+    def _open_stream(self, trace_id: str, remaining_ms: int) -> dict:
+        req = Request(
+            self._subscribe_url(trace_id),
+            headers={
+                "Authorization": f"Bearer {self._config.api_token}",
+                "Accept": "text/event-stream",
+            },
+            method="GET",
+        )
+        try:
+            resp = urlopen(req, timeout=remaining_ms / 1000)  # noqa: S310
+            return {"kind": "opened", "response": resp}
+        except SdkTimeoutError:
+            raise
+        except TimeoutError as err:
+            raise SdkTimeoutError(
+                "subscribeExecution", int(remaining_ms / 1000) or 1
+            ) from err
+        except HTTPError as err:
+            if err.fp:
+                err.fp.read()
+            return {"kind": "http", "status": err.code}
+        except URLError:
+            return {"kind": "network"}
+
+    def _read_stream(self, resp: object) -> dict:
+        chunks: list[str] = []
+        event_count = 0
+        completed = False
+        dropped = False
+        buffer = ""
+        try:
+            while True:
+                line = resp.readline()  # type: ignore[attr-defined]
+                if not line:
+                    dropped = not completed
+                    break
+                buffer += line.decode("utf-8", errors="replace")
+                if "\n\n" not in buffer:
+                    continue
+                frames = buffer.split("\n\n")
+                buffer = frames.pop()
+
+                def on_frame(frame: str) -> None:
+                    nonlocal event_count
+                    event_count += 1
+                    chunks.append(frame[:500])
+
+                done_now, _ = consume_subscribe_frames(frames, on_frame)
+                if done_now:
+                    completed = True
+                    break
+        finally:
+            close = getattr(resp, "close", None)
+            if callable(close):
+                close()
+        return {
+            "completed": completed,
+            "event_count": event_count,
+            "chunks": chunks,
+            "dropped": dropped,
+        }
+
+    def _after_stream_success(
+        self,
+        trace_id: str,
+        event_count: int,
+        chunks: list[str],
+        remaining_ms: int,
+    ) -> SubscribeCompleteResult:
+        stream_snippet = "\n---\n".join(chunks[-5:])
+        if remaining_ms <= 100:
+            return SubscribeCompleteResult(
+                ok=False,
+                event_count=event_count,
+                raw_snippet="execution status=deadline",
+            )
+        confirmed = self._confirm_execution_settled(trace_id, remaining_ms)
+        if not confirmed.ok:
+            return SubscribeCompleteResult(
+                ok=False,
+                event_count=event_count,
+                raw_snippet=confirmed.raw_snippet,
+            )
+        return SubscribeCompleteResult(
+            ok=True,
+            event_count=event_count,
+            raw_snippet=stream_snippet or "successful run terminal",
+        )
+
+    def _fail_open(
+        self, event_count: int, reconnects: int, status_label: str
+    ) -> SubscribeCompleteResult:
+        snippet = (
+            f"subscribe reconnect {reconnects} status={status_label}"
+            if reconnects > 0
+            else f"subscribe status={status_label}"
+        )
+        return SubscribeCompleteResult(
+            ok=False, event_count=event_count, raw_snippet=snippet
+        )
+
+    def _fail_stream(
+        self,
+        event_count: int,
+        chunks: list[str],
+        reconnects: int,
+        last_open_failure: str,
+    ) -> SubscribeCompleteResult:
+        if last_open_failure:
+            return self._fail_open(event_count, reconnects, last_open_failure)
+        stream_snippet = "\n---\n".join(chunks[-5:])
+        return SubscribeCompleteResult(
+            ok=False,
+            event_count=event_count,
+            raw_snippet=(
+                f"subscribe EOF without successful terminal after {reconnects} reconnect(s)"
+                if reconnects > 0
+                else stream_snippet or "subscribe EOF without successful terminal"
+            ),
+        )
+
+    def _confirm_execution_settled(
+        self, trace_id: str, timeout_ms: int
+    ) -> SubscribeCompleteResult:
+        deadline = time.monotonic() + timeout_ms / 1000
+        url = (
+            f"{self._config.aiden_url()}/api/v1/executions/{trace_id}"
+            f"{_http.query(self._config.org_id)}"
+        )
+        poll_interval = self._config.poll_interval_seconds
+        last_transient = ""
+        while time.monotonic() < deadline:
+            try:
+                data = _http.request(url, self._config.api_token, retries=1)
+                if not isinstance(data, dict):
+                    last_transient = "execution status=invalid_payload"
+                else:
+                    last_transient = ""
+                    execution = data.get("execution") or {}
+                    status = ExecutionStatus.parse(
+                        _http.text(execution.get("status"))
+                    )
+                    settled = execution.get("trace_settled")
+                    ready = (
+                        status is not None
+                        and status.is_terminal()
+                        and settled is not False
+                    )
+                    if ready:
+                        if status in {
+                            ExecutionStatus.ERROR,
+                            ExecutionStatus.FAILED,
+                            ExecutionStatus.CANCELLED,
+                        }:
+                            return SubscribeCompleteResult(
+                                ok=False,
+                                event_count=0,
+                                raw_snippet=f"execution status={status.value}",
+                            )
+                        return SubscribeCompleteResult(
+                            ok=True,
+                            event_count=0,
+                            raw_snippet="successful run terminal",
+                        )
+            except HttpError as err:
+                if not _http.is_transient_http_error(err):
+                    code = err.status_code if err.status_code is not None else "error"
+                    return SubscribeCompleteResult(
+                        ok=False,
+                        event_count=0,
+                        raw_snippet=f"execution status={code}",
+                    )
+                last_transient = f"execution {_http.http_status_snippet(err)}"
+            remaining = deadline - time.monotonic()
+            if remaining <= 0.1:
+                break
+            time.sleep(min(poll_interval, remaining - 0.1))
+        return SubscribeCompleteResult(
+            ok=False,
+            event_count=0,
+            raw_snippet=last_transient or f"subscribe aborted after {timeout_ms}ms",
+        )

stackgen_sdk-0.4.0rc9/src/stackgen/aiden/subscribe_frames.py

@@ -0,0 +1,50 @@
+"""Domain interpretation of Aiden execution subscribe SSE frames.
+
+The wire format is CloudEvents / AG-UI text frames. This module only answers:
+"did this frame say the execution finished successfully?" — no I/O.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Literal
+
+SubscribeFrameKind = Literal["success", "error", "continue"]
+
+
+def classify_subscribe_frame(frame: str) -> SubscribeFrameKind:
+    """Classify one SSE event payload (text between blank lines).
+
+    Success: ``execution_complete``, or ``subscribe_end`` without an error marker.
+    """
+    lower = frame.lower()
+    if not lower.strip():
+        return "continue"
+    if '"type":"error"' in lower or "event: error" in lower:
+        return "error"
+    if "execution_complete" in lower:
+        return "success"
+    if "subscribe_end" in lower and "error" not in lower:
+        return "success"
+    return "continue"
+
+
+def consume_subscribe_frames(
+    frames: list[str],
+    on_frame: Callable[[str], None] | None = None,
+) -> tuple[bool, bool]:
+    """Accumulate frames; return ``(completed, saw_error)``."""
+    completed = False
+    saw_error = False
+    for frame in frames:
+        if not frame.strip():
+            continue
+        if on_frame is not None:
+            on_frame(frame)
+        kind = classify_subscribe_frame(frame)
+        if kind == "success":
+            completed = True
+            break
+        if kind == "error":
+            saw_error = True
+    return completed, saw_error

stackgen_sdk-0.4.0rc9/src/stackgen/aiden/transient.py

@@ -0,0 +1,73 @@
+"""Platform-blip policy for Aiden waits.
+
+Domain rules (not HTTP mechanics):
+
+- A *transient* failure is one the platform may self-heal during a short
+  rollout or gateway drop: HTTP 429, any 5xx, or a lost connection.
+- Non-retryable 4xx and real execution terminals stay fail-fast.
+- 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.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from typing import TypeVar
+
+from stackgen import _http
+
+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).
+IDEMPOTENT_MUTATION_ATTEMPTS = 3
+
+# Backoff base (seconds) between idempotent mutation attempts: 0.5, 1.0, …
+IDEMPOTENT_MUTATION_BACKOFF_SECONDS = 0.5
+
+
+def is_transient_status(status: int) -> bool:
+    """True when an HTTP status is a self-healing platform blip."""
+    return _http.is_retryable_http_status(status)
+
+
+def is_transient_failure(err: BaseException) -> bool:
+    """True when an error is a self-healing blip (status or transport)."""
+    return _http.is_transient_http_error(err)
+
+
+def transient_status_label(status: int | None = None, *, network: bool = False) -> str:
+    """Human label for failure snippets (``500``, ``network_error``)."""
+    if network or status is None:
+        return "network_error"
+    return str(status)
+
+
+def retry_idempotent_op(
+    op: Callable[[], T],
+    *,
+    attempts: int = IDEMPOTENT_MUTATION_ATTEMPTS,
+    backoff_seconds: float = IDEMPOTENT_MUTATION_BACKOFF_SECONDS,
+    sleep: Callable[[float], None] | None = None,
+) -> T:
+    """Run an idempotent operation with bounded retries on transient failures.
+
+    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
+    last_err: BaseException | None = None
+    for attempt in range(1, attempts + 1):
+        try:
+            return op()
+        except Exception as err:
+            last_err = err
+            if not is_transient_failure(err) or attempt >= attempts:
+                raise
+            sleeper(backoff_seconds * attempt)
+    assert last_err is not None
+    raise last_err

{stackgen_sdk-0.4.0rc8 → stackgen_sdk-0.4.0rc9}/src/stackgen/aiden/webhook_ops.py

@@ -9,6 +9,7 @@ from typing import Any
 
 from stackgen import _http
 from stackgen.aiden.runs import WebhookRunPoller
+from stackgen.aiden.transient import retry_idempotent_op
 from stackgen.config import StackgenConfig
 from stackgen.errors import StackgenError
 
@@ -157,7 +158,12 @@ class WebhookOps:
         return data
 
     def terminate_session(self, session_id: str, *, reason: str | None = None) -> dict[str, Any]:
-        """POST /guild/api/v1/sessions/{sessionId}/terminate."""
+        """Cancel running work for a session (POST …/sessions/{id}/terminate).
+
+        Idempotent on the Guild API, so transient platform blips are retried via
+        :func:`~stackgen.aiden.transient.retry_idempotent_op`. Do not treat
+        webhook/workflow starts the same way.
+        """
         query: dict[str, Any] = {}
         if self._config.org_id:
             query["orgId"] = self._config.org_id
@@ -167,10 +173,16 @@ class WebhookOps:
             f"{self._config.aiden_url()}/api/v1/sessions/{session_id}/terminate"
             f"{_query_string(query)}"
         )
-        data = _http.request(url, self._config.api_token, method="POST")
-        if not isinstance(data, dict):
-            raise StackgenError(f"unexpected terminate session payload: {data!r}")
-        return data
+
+        def once() -> dict[str, Any]:
+            data = _http.request(
+                url, self._config.api_token, method="POST", retries=1
+            )
+            if not isinstance(data, dict):
+                raise StackgenError(f"unexpected terminate session payload: {data!r}")
+            return data
+
+        return retry_idempotent_op(once)
 
     def start_workflow_run(
         self,

stackgen_sdk-0.4.0rc8/src/stackgen/aiden/subscribe.py

@@ -1,174 +0,0 @@
-"""SSE subscribeExecution helper."""
-
-from __future__ import annotations
-
-import time
-from dataclasses import dataclass
-from urllib.error import HTTPError, URLError
-from urllib.request import Request, urlopen
-
-from stackgen import _http
-from stackgen.aiden.run_status import ExecutionStatus
-from stackgen.config import StackgenConfig
-from stackgen.errors import HttpError, TimeoutError as SdkTimeoutError
-
-
-@dataclass
-class SubscribeCompleteResult:
-    ok: bool
-    event_count: int
-    raw_snippet: str
-
-
-class ExecutionSubscribe:
-    def __init__(self, config: StackgenConfig) -> None:
-        self._config = config
-
-    def wait_for_complete(
-        self, trace_id: str, *, timeout_ms: int = 10 * 60 * 1000
-    ) -> SubscribeCompleteResult:
-        started = time.monotonic()
-        url = (
-            f"{self._config.aiden_url()}/api/v1/executions/{trace_id}/subscribe"
-            + _http.query(self._config.org_id)
-        )
-        req = Request(
-            url,
-            headers={
-                "Authorization": f"Bearer {self._config.api_token}",
-                "Accept": "text/event-stream",
-            },
-            method="GET",
-        )
-        chunks: list[str] = []
-        event_count = 0
-        ok = False
-        try:
-            with urlopen(req, timeout=timeout_ms / 1000) as resp:  # noqa: S310
-                buffer = ""
-                while True:
-                    line = resp.readline()
-                    if not line:
-                        break
-                    buffer += line.decode("utf-8", errors="replace")
-                    if "\n\n" not in buffer:
-                        continue
-                    frames = buffer.split("\n\n")
-                    buffer = frames.pop()
-                    for frame in frames:
-                        if not frame.strip():
-                            continue
-                        event_count += 1
-                        chunks.append(frame[:500])
-                        lower = frame.lower()
-                        if "execution_complete" in lower:
-                            ok = True
-                            break
-                        if "subscribe_end" in lower and "error" not in lower:
-                            ok = True
-                    if ok:
-                        break
-        except SdkTimeoutError:
-            raise
-        except TimeoutError as err:
-            raise SdkTimeoutError("subscribeExecution", int(timeout_ms / 1000)) from err
-        except HTTPError as err:
-            detail = err.read().decode("utf-8", errors="replace") if err.fp else ""
-            raise HttpError(
-                f"subscribeExecution -> HTTP {err.code}: {detail}",
-                status_code=err.code,
-            ) from err
-        except URLError as err:
-            raise HttpError(f"subscribeExecution -> {err}") from err
-
-        stream_snippet = "\n---\n".join(chunks[-5:])
-        if not ok:
-            return SubscribeCompleteResult(
-                ok=False,
-                event_count=event_count,
-                raw_snippet=stream_snippet,
-            )
-
-        remaining_ms = timeout_ms - int((time.monotonic() - started) * 1000)
-        if remaining_ms <= 100:
-            return SubscribeCompleteResult(
-                ok=False,
-                event_count=event_count,
-                raw_snippet="execution status=deadline",
-            )
-
-        confirmed = self._confirm_execution_settled(trace_id, remaining_ms)
-        if not confirmed.ok:
-            return SubscribeCompleteResult(
-                ok=False,
-                event_count=event_count,
-                raw_snippet=confirmed.raw_snippet,
-            )
-        return SubscribeCompleteResult(
-            ok=True,
-            event_count=event_count,
-            raw_snippet=stream_snippet or "successful run terminal",
-        )
-
-    def _confirm_execution_settled(
-        self, trace_id: str, timeout_ms: int
-    ) -> SubscribeCompleteResult:
-        """Poll GET /executions/{traceId} until settled inside the remaining deadline."""
-        deadline = time.monotonic() + timeout_ms / 1000
-        url = (
-            f"{self._config.aiden_url()}/api/v1/executions/{trace_id}"
-            f"{_http.query(self._config.org_id)}"
-        )
-        poll_interval = self._config.poll_interval_seconds
-        last_transient = ""
-        while time.monotonic() < deadline:
-            try:
-                data = _http.request(url, self._config.api_token, retries=1)
-                if not isinstance(data, dict):
-                    last_transient = "execution status=invalid_payload"
-                else:
-                    last_transient = ""
-                    execution = data.get("execution") or {}
-                    status = ExecutionStatus.parse(
-                        _http.text(execution.get("status"))
-                    )
-                    settled = execution.get("trace_settled")
-                    ready = (
-                        status is not None
-                        and status.is_terminal()
-                        and settled is not False
-                    )
-                    if ready:
-                        if status in {
-                            ExecutionStatus.ERROR,
-                            ExecutionStatus.FAILED,
-                            ExecutionStatus.CANCELLED,
-                        }:
-                            return SubscribeCompleteResult(
-                                ok=False,
-                                event_count=0,
-                                raw_snippet=f"execution status={status.value}",
-                            )
-                        return SubscribeCompleteResult(
-                            ok=True,
-                            event_count=0,
-                            raw_snippet="successful run terminal",
-                        )
-            except HttpError as err:
-                if not _http.is_transient_http_error(err):
-                    code = err.status_code if err.status_code is not None else "error"
-                    return SubscribeCompleteResult(
-                        ok=False,
-                        event_count=0,
-                        raw_snippet=f"execution status={code}",
-                    )
-                last_transient = f"execution {_http.http_status_snippet(err)}"
-            remaining = deadline - time.monotonic()
-            if remaining <= 0.1:
-                break
-            time.sleep(min(poll_interval, remaining - 0.1))
-        return SubscribeCompleteResult(
-            ok=False,
-            event_count=0,
-            raw_snippet=last_transient or f"subscribe aborted after {timeout_ms}ms",
-        )