stackgen-sdk 0.1.5__tar.gz → 0.1.6__tar.gz

{stackgen_sdk-0.1.5 → stackgen_sdk-0.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: stackgen-sdk
-Version: 0.1.5
+Version: 0.1.6
 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/
@@ -37,7 +37,7 @@ from stackgen import StackgenClient, StackgenConfig
 
 client = StackgenClient(
     StackgenConfig(
-        base_url="https://azure-eu.cloud.stackgen.com",
+        base_url="https://app.stackgen.com",
         api_token="stackgen_…",
         org_id="<project-uuid>",
         webhook_token="sg_aios_…",  # webhook journeys only

{stackgen_sdk-0.1.5 → stackgen_sdk-0.1.6}/README.md

@@ -16,7 +16,7 @@ from stackgen import StackgenClient, StackgenConfig
 
 client = StackgenClient(
     StackgenConfig(
-        base_url="https://azure-eu.cloud.stackgen.com",
+        base_url="https://app.stackgen.com",
         api_token="stackgen_…",
         org_id="<project-uuid>",
         webhook_token="sg_aios_…",  # webhook journeys only

{stackgen_sdk-0.1.5 → stackgen_sdk-0.1.6}/src/stackgen/__init__.py

@@ -6,7 +6,7 @@ Public entrypoint::
 
     client = StackgenClient(
         StackgenConfig(
-            base_url="https://azure-eu.cloud.stackgen.com",
+            base_url="https://app.stackgen.com",
             api_token="stackgen_…",
             org_id="<project-uuid>",
         )
@@ -18,14 +18,32 @@ from __future__ import annotations
 from stackgen.client import StackgenClient
 from stackgen.config import StackgenConfig
 from stackgen.errors import HttpError, NotAllowlistedError, StackgenError, TimeoutError
+from stackgen.aiden.workflow_builder import (
+    AgentDefinition,
+    StageDefinition,
+    WorkflowBuilder,
+    WorkflowDefinition,
+    create_agent,
+    create_stage,
+    create_workflow,
+)
+from stackgen.aiden.workflow_publish import PublishWorkflowResult
 
 __all__ = [
+    "AgentDefinition",
     "HttpError",
     "NotAllowlistedError",
+    "PublishWorkflowResult",
     "StackgenClient",
     "StackgenConfig",
     "StackgenError",
+    "StageDefinition",
     "TimeoutError",
+    "WorkflowBuilder",
+    "WorkflowDefinition",
+    "create_agent",
+    "create_stage",
+    "create_workflow",
 ]
 
 

{stackgen_sdk-0.1.5 → stackgen_sdk-0.1.6}/src/stackgen/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.5'
-__version_tuple__ = version_tuple = (0, 1, 5)
+__version__ = version = '0.1.6'
+__version_tuple__ = version_tuple = (0, 1, 6)
 
 __commit_id__ = commit_id = None

stackgen_sdk-0.1.6/src/stackgen/aiden/__init__.py

@@ -0,0 +1,29 @@
+"""Aiden (platform) namespace — webhooks, sessions, artifacts, Ask Guild, workflows."""
+
+from stackgen.aiden.ask import AskArtifactResult
+from stackgen.aiden.namespace import AidenNamespace
+from stackgen.aiden.webhook import WebhookReportResult
+from stackgen.aiden.workflow_builder import (
+    AgentDefinition,
+    StageDefinition,
+    WorkflowBuilder,
+    WorkflowDefinition,
+    create_agent,
+    create_stage,
+    create_workflow,
+)
+from stackgen.aiden.workflow_publish import PublishWorkflowResult
+
+__all__ = [
+    "AgentDefinition",
+    "AidenNamespace",
+    "AskArtifactResult",
+    "PublishWorkflowResult",
+    "StageDefinition",
+    "WebhookReportResult",
+    "WorkflowBuilder",
+    "WorkflowDefinition",
+    "create_agent",
+    "create_stage",
+    "create_workflow",
+]

{stackgen_sdk-0.1.5 → stackgen_sdk-0.1.6}/src/stackgen/aiden/ask.py

@@ -157,8 +157,12 @@ class AskArtifactJourney:
                 raise StackgenError(f"unexpected getExecutionTrace payload: {data!r}")
             execution = data.get("execution") or {}
             status = _http.text(execution.get("status")).casefold()
-            trace_settled = execution.get("trace_settled") is True
-            if trace_settled and status in _TERMINAL_STATUSES:
+            # Prefer explicit settle when the mothership sends it. Some builds
+            # omit trace_settled on the thin getExecutionTrace summary; treat
+            # terminal status alone as done so callers are not stuck forever.
+            settled = execution.get("trace_settled")
+            ready = status in _TERMINAL_STATUSES and settled is not False
+            if ready:
                 if status == "error":
                     raise StackgenError(
                         f"execution {trace_id} ended with status error"

stackgen_sdk-0.1.6/src/stackgen/aiden/namespace.py

@@ -0,0 +1,170 @@
+"""Aiden namespace — public methods for platform APIs."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from stackgen.aiden.ask import AskArtifactJourney, AskArtifactResult
+from stackgen.aiden.webhook import WebhookReportJourney, WebhookReportResult
+from stackgen.aiden.webhook_ops import WebhookOps
+from stackgen.aiden.workflow_builder import AgentDefinition, WorkflowDefinition
+from stackgen.aiden.workflow_publish import PublishWorkflowResult, WorkflowPublishJourney
+from stackgen.config import StackgenConfig
+
+
+class AidenNamespace:
+    """Aiden platform APIs (sessions, webhooks, artifacts, Ask Guild, workflows)."""
+
+    def __init__(self, config: StackgenConfig) -> None:
+        self._config = config
+        self._webhook = WebhookReportJourney(config)
+        self._ask = AskArtifactJourney(config)
+        self._workflows = WorkflowPublishJourney(config)
+        self._webhook_ops = WebhookOps(config)
+
+    def run_webhook_and_download_report(
+        self,
+        payload: str,
+        *,
+        artifact_name: str | None = None,
+        output_path: str | None = None,
+    ) -> WebhookReportResult:
+        """Trigger a webhook, wait for the session artifact, download it."""
+        return self._webhook.run(
+            payload, artifact_name=artifact_name, output_path=output_path
+        )
+
+    def trigger_webhook(self, payload: str) -> dict[str, Any]:
+        """POST /guild/api/v1/webhooks/trigger (stateless; returns 202 body)."""
+        return self._webhook_ops.trigger_webhook(payload)
+
+    def get_webhook_run(self, webhook_id: str, invocation_id: str) -> dict[str, Any]:
+        """GET webhook invocation detail by invocation UUID."""
+        return self._webhook_ops.get_webhook_run(webhook_id, invocation_id)
+
+    def list_webhook_runs(self, webhook_id: str) -> list[dict[str, Any]]:
+        """List webhook invocations for a webhook id."""
+        return self._webhook_ops.list_webhook_runs(webhook_id)
+
+    def wait_for_webhook_session(
+        self,
+        webhook_id: str,
+        invocation_id: str,
+        *,
+        dispatch_run_id: str = "",
+        known_run_ids: frozenset[str] | None = None,
+    ) -> str:
+        """Poll webhook run detail until session_id is set."""
+        return self._webhook_ops.wait_for_webhook_session(
+            webhook_id,
+            invocation_id,
+            dispatch_run_id=dispatch_run_id,
+            known_run_ids=known_run_ids,
+        )
+
+    def get_execution_trace(self, trace_id: str) -> dict[str, Any]:
+        """GET /guild/api/v1/executions/{traceId}."""
+        return self._webhook_ops.get_execution_trace(trace_id)
+
+    def list_executions(self, **params: Any) -> list[dict[str, Any]]:
+        """GET /guild/api/v1/executions (optional session_id filter)."""
+        return self._webhook_ops.list_executions(**params)
+
+    def list_sessions(self, **params: Any) -> dict[str, Any]:
+        """GET /guild/api/v1/sessions (search with q / source_app)."""
+        return self._webhook_ops.list_sessions(**params)
+
+    def get_session(self, session_id: str) -> dict[str, Any]:
+        """GET /guild/api/v1/sessions/{sessionId}."""
+        return self._webhook_ops.get_session(session_id)
+
+    def list_session_artifacts(self, session_id: str) -> list[dict[str, Any]]:
+        """GET session artifact metadata list."""
+        return self._webhook_ops.list_session_artifacts(session_id)
+
+    def download_session_artifact(
+        self,
+        session_id: str,
+        artifact_name: str,
+        output_path: str,
+    ) -> Path:
+        """Download one session artifact to a local path."""
+        return self._webhook_ops.download_session_artifact(
+            session_id, artifact_name, output_path
+        )
+
+    def export_session(
+        self,
+        session_id: str,
+        *,
+        parts: str | None = None,
+        format: str = "json",
+    ) -> dict[str, Any]:
+        """GET /guild/api/v1/sessions/{sessionId}/export (report / notes / evidence)."""
+        return self._webhook_ops.export_session(session_id, parts=parts, format=format)
+
+    def terminate_session(self, session_id: str, *, reason: str | None = None) -> dict[str, Any]:
+        """POST /guild/api/v1/sessions/{sessionId}/terminate."""
+        return self._webhook_ops.terminate_session(session_id, reason=reason)
+
+    def run_ask_and_download_artifact(
+        self,
+        message: str,
+        *,
+        entity_refs: list[dict[str, str]] | None = None,
+        artifact_name: str | None = None,
+        output_path: str | None = None,
+        inputs: dict[str, str] | None = None,
+        session_id: str | None = None,
+        source_app: str | None = None,
+        source_metadata: dict[str, str] | None = None,
+    ) -> AskArtifactResult:
+        """Start Ask Guild, poll execution, wait for artifact, download it."""
+        return self._ask.run(
+            message,
+            entity_refs=entity_refs,
+            artifact_name=artifact_name,
+            output_path=output_path,
+            inputs=inputs,
+            session_id=session_id,
+            source_app=source_app,
+            source_metadata=source_metadata,
+        )
+
+    def start_ask(
+        self,
+        message: str,
+        *,
+        entity_refs: list[dict[str, str]] | None = None,
+        inputs: dict[str, str] | None = None,
+        session_id: str | None = None,
+        source_app: str | None = None,
+        source_metadata: dict[str, str] | None = None,
+    ) -> dict[str, Any]:
+        """POST /guild/api/v1/guild/ask/start (advanced callers)."""
+        return self._ask.start_ask(
+            message,
+            entity_refs=entity_refs,
+            inputs=inputs,
+            session_id=session_id,
+            source_app=source_app,
+            source_metadata=source_metadata,
+        )
+
+    def wait_for_execution(self, trace_id: str) -> dict[str, Any]:
+        """Poll GET /guild/api/v1/executions/{traceId} until settled."""
+        return self._ask.wait_for_execution(trace_id)
+
+    def publish_workflow(
+        self,
+        workflow: WorkflowDefinition,
+        *,
+        agents: list[AgentDefinition] | None = None,
+        approve: bool = True,
+    ) -> PublishWorkflowResult:
+        """Register/update agents and create/update a workflow, optionally approving it.
+
+        Pass a committed builder from ``create_workflow(...).then(...).commit()``.
+        """
+        return self._workflows.publish(workflow, agents=agents, approve=approve)

stackgen_sdk-0.1.6/src/stackgen/aiden/runs.py

@@ -0,0 +1,137 @@
+"""Webhook run polling and selection helpers."""
+
+from __future__ import annotations
+
+import json
+import time
+from typing import Any
+
+from stackgen import _http
+from stackgen.config import StackgenConfig
+from stackgen.errors import StackgenError, TimeoutError
+
+
+def pick_run(
+    runs: list[dict[str, Any]],
+    dispatch_run_id: str,
+    known_run_ids: frozenset[str],
+) -> dict[str, Any] | None:
+    """Choose the webhook run that corresponds to a new trigger.
+
+    Preference order:
+      1. Exact match on ``id`` / ``run_id`` to ``dispatch_run_id``
+      2. First run whose id is not in ``known_run_ids`` (new since pre-trigger snapshot)
+      3. If no known ids and runs exist, the first run (best-effort fallback)
+    """
+    if dispatch_run_id:
+        for item in runs:
+            if dispatch_run_id in {
+                _http.text(item.get("id")),
+                _http.text(item.get("run_id")),
+            }:
+                return item
+    for item in runs:
+        if _http.text(item.get("id")) not in known_run_ids:
+            return item
+    if not runs:
+        return None
+    if not known_run_ids:
+        return runs[0]
+    return None
+
+
+class WebhookRunPoller:
+    """Poll webhook invocation rows until a session_id is available.
+
+    Mirrors the dual-path flow in Guild's webhook_session_artifact reference script.
+    """
+
+    def __init__(self, config: StackgenConfig) -> None:
+        self._config = config
+
+    def resolve_ids(
+        self, trigger: dict[str, Any]
+    ) -> tuple[str, str]:
+        """Pick webhook_id and invocation_id from the 202 body or config."""
+        cfg = self._config
+        webhook_id = _http.text(trigger.get("webhook_id")) or _http.text(cfg.webhook_id)
+        invocation_id = _http.text(trigger.get("invocation_id"))
+        if webhook_id:
+            return webhook_id, invocation_id
+        if _http.text(trigger.get("session_id")):
+            return "", invocation_id
+        raise StackgenError(
+            "trigger 202 did not include session_id or webhook_id; "
+            "set webhook_id for older motherships that only return run_id. "
+            f"body={json.dumps(trigger)}"
+        )
+
+    def get_run(self, webhook_id: str, run_id: str) -> dict[str, Any]:
+        """GET one webhook invocation (invocation UUID, not Temporal run_id)."""
+        url = (
+            f"{self._config.aiden_url()}/api/v1/webhooks/{webhook_id}/runs/{run_id}"
+            f"{_http.query(self._config.org_id)}"
+        )
+        data = _http.request(url, self._config.api_token)
+        if not isinstance(data, dict):
+            raise StackgenError(f"unexpected run payload: {data!r}")
+        return data
+
+    def list_runs(self, webhook_id: str) -> list[dict[str, Any]]:
+        """List invocations for a webhook."""
+        url = (
+            f"{self._config.aiden_url()}/api/v1/webhooks/{webhook_id}/runs"
+            f"{_http.query(self._config.org_id)}"
+        )
+        return _http.as_list(_http.request(url, self._config.api_token))
+
+    def snapshot_known_run_ids(self, webhook_id: str) -> frozenset[str]:
+        """Capture invocation ids before trigger for older mothership matching."""
+        return frozenset(
+            _http.text(item.get("id"))
+            for item in self.list_runs(webhook_id)
+            if _http.text(item.get("id"))
+        )
+
+    def wait_for_session(
+        self,
+        webhook_id: str,
+        invocation_id: str,
+        dispatch_run_id: str = "",
+        known_run_ids: frozenset[str] | None = None,
+    ) -> str:
+        """Poll the webhook invocation until Aiden attaches a session_id."""
+        cfg = self._config
+        known = known_run_ids if known_run_ids is not None else frozenset()
+        deadline = time.monotonic() + cfg.timeout_seconds
+        run_id_hint = invocation_id or dispatch_run_id
+        while time.monotonic() < deadline:
+            run: dict[str, Any] | None = None
+            if run_id_hint:
+                try:
+                    run = self.get_run(webhook_id, run_id_hint)
+                except StackgenError:
+                    run = None
+            if run is None:
+                run = pick_run(
+                    self.list_runs(webhook_id),
+                    dispatch_run_id,
+                    known,
+                )
+            if run is None:
+                time.sleep(cfg.poll_interval_seconds)
+                continue
+            if not run_id_hint:
+                run_id_hint = _http.text(run.get("id")) or _http.text(run.get("run_id"))
+
+            status = _http.text(run.get("status")).casefold()
+            session_id = _http.text(run.get("session_id"))
+            if status in {"failed", "skipped"}:
+                raise StackgenError(
+                    f"webhook invocation ended with status {status}: "
+                    f"{run.get('error') or 'no error detail'}"
+                )
+            if session_id:
+                return session_id
+            time.sleep(cfg.poll_interval_seconds)
+        raise TimeoutError("webhook session", cfg.timeout_seconds)

{stackgen_sdk-0.1.5 → stackgen_sdk-0.1.6}/src/stackgen/aiden/webhook.py

@@ -2,15 +2,15 @@
 
 from __future__ import annotations
 
-import json
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
 from stackgen import _http
 from stackgen.aiden import sessions as session_helpers
+from stackgen.aiden.runs import WebhookRunPoller
+from stackgen.aiden.webhook_ops import WebhookOps
 from stackgen.config import StackgenConfig
-from stackgen.errors import StackgenError
 
 
 @dataclass(frozen=True)
@@ -28,10 +28,14 @@ class WebhookReportJourney:
     """Trigger a webhook, wait for the session artifact, and download it.
 
     Uses ``webhook_token`` for POST trigger and ``api_token`` for poll/download.
+    When the 202 body includes ``session_id``, skips run polling. Otherwise polls
+    GET webhook run detail until ``session_id`` is available.
     """
 
     def __init__(self, config: StackgenConfig) -> None:
         self._config = config
+        self._ops = WebhookOps(config)
+        self._poller = WebhookRunPoller(config)
 
     def run(
         self,
@@ -47,14 +51,19 @@ class WebhookReportJourney:
         artifact = artifact_name or cfg.artifact_name
         dest = output_path or cfg.output_path
 
-        trigger = self._trigger(payload)
-        webhook_id = _http.text(trigger.get("webhook_id")) or _http.text(cfg.webhook_id)
-        invocation_id = _http.text(trigger.get("invocation_id"))
-        session_id = _http.text(trigger.get("session_id"))
+        known_run_ids = frozenset[str]()
+        if cfg.webhook_id:
+            known_run_ids = self._poller.snapshot_known_run_ids(cfg.webhook_id)
 
+        trigger = self._ops.trigger_webhook(payload)
+        webhook_id, invocation_id = self._poller.resolve_ids(trigger)
+        session_id = _http.text(trigger.get("session_id"))
         if not session_id:
-            raise StackgenError(
-                f"trigger response missing session_id; body={json.dumps(trigger)}"
+            session_id = self._poller.wait_for_session(
+                webhook_id,
+                invocation_id,
+                _http.text(trigger.get("run_id")),
+                known_run_ids,
             )
 
         artifacts = session_helpers.wait_for_artifact(cfg, session_id, artifact)
@@ -66,16 +75,3 @@ class WebhookReportJourney:
             artifacts=tuple(artifacts),
             output_path=path,
         )
-
-    def _trigger(self, payload: str) -> dict[str, Any]:
-        url = f"{self._config.aiden_url()}/api/v1/webhooks/trigger{_http.query(self._config.org_id)}"
-        data = _http.request(
-            url,
-            self._config.webhook_token,
-            method="POST",
-            body=payload.encode("utf-8"),
-            content_type="text/plain",
-        )
-        if not isinstance(data, dict):
-            raise StackgenError(f"unexpected trigger payload: {data!r}")
-        return data

stackgen_sdk-0.1.6/src/stackgen/aiden/webhook_ops.py

@@ -0,0 +1,172 @@
+"""Stateless Aiden webhook and session artifact API helpers."""
+
+from __future__ import annotations
+
+import urllib.parse
+from pathlib import Path
+from typing import Any
+
+from stackgen import _http
+from stackgen.aiden.runs import WebhookRunPoller
+from stackgen.config import StackgenConfig
+from stackgen.errors import StackgenError
+
+
+def _query_string(params: dict[str, Any]) -> str:
+    cleaned = {k: v for k, v in params.items() if v is not None and v != ""}
+    if not cleaned:
+        return ""
+    return "?" + urllib.parse.urlencode(cleaned)
+
+
+class WebhookOps:
+    """One-shot webhook trigger, run polling, execution trace, and artifact APIs."""
+
+    def __init__(self, config: StackgenConfig) -> None:
+        self._config = config
+        self._poller = WebhookRunPoller(config)
+
+    def trigger_webhook(self, payload: str) -> dict[str, Any]:
+        """POST /guild/api/v1/webhooks/trigger using the webhook token."""
+        cfg = self._config
+        if not cfg.webhook_token:
+            raise ValueError("webhook_token is required for trigger_webhook")
+        url = f"{cfg.aiden_url()}/api/v1/webhooks/trigger{_http.query(cfg.org_id)}"
+        data = _http.request(
+            url,
+            cfg.webhook_token,
+            method="POST",
+            body=payload.encode("utf-8"),
+            content_type="text/plain",
+        )
+        if not isinstance(data, dict):
+            raise StackgenError(f"unexpected trigger payload: {data!r}")
+        return data
+
+    def get_webhook_run(self, webhook_id: str, invocation_id: str) -> dict[str, Any]:
+        """GET /guild/api/v1/webhooks/{webhook_id}/runs/{invocation_id}."""
+        return self._poller.get_run(webhook_id, invocation_id)
+
+    def list_webhook_runs(self, webhook_id: str) -> list[dict[str, Any]]:
+        """GET /guild/api/v1/webhooks/{webhook_id}/runs."""
+        return self._poller.list_runs(webhook_id)
+
+    def wait_for_webhook_session(
+        self,
+        webhook_id: str,
+        invocation_id: str,
+        *,
+        dispatch_run_id: str = "",
+        known_run_ids: frozenset[str] | None = None,
+    ) -> str:
+        """Poll webhook run detail until session_id is set."""
+        return self._poller.wait_for_session(
+            webhook_id,
+            invocation_id,
+            dispatch_run_id,
+            known_run_ids,
+        )
+
+    def get_execution_trace(self, trace_id: str) -> dict[str, Any]:
+        """GET /guild/api/v1/executions/{traceId}."""
+        url = (
+            f"{self._config.aiden_url()}/api/v1/executions/{trace_id}"
+            f"{_http.query(self._config.org_id)}"
+        )
+        data = _http.request(url, self._config.api_token)
+        if not isinstance(data, dict):
+            raise StackgenError(f"unexpected execution trace payload: {data!r}")
+        return data
+
+    def list_executions(self, **params: Any) -> list[dict[str, Any]]:
+        """GET /guild/api/v1/executions (optional session_id, agent_name, limit, offset)."""
+        query = dict(params)
+        if self._config.org_id and "orgId" not in query:
+            query["orgId"] = self._config.org_id
+        url = f"{self._config.aiden_url()}/api/v1/executions{_query_string(query)}"
+        return _http.as_list(_http.request(url, self._config.api_token))
+
+    def list_sessions(self, **params: Any) -> dict[str, Any]:
+        """GET /guild/api/v1/sessions (optional q, source_app, limit, offset)."""
+        query = dict(params)
+        if self._config.org_id and "orgId" not in query:
+            query["orgId"] = self._config.org_id
+        url = f"{self._config.aiden_url()}/api/v1/sessions{_query_string(query)}"
+        data = _http.request(url, self._config.api_token)
+        if not isinstance(data, dict):
+            raise StackgenError(f"unexpected session list payload: {data!r}")
+        return data
+
+    def get_session(self, session_id: str) -> dict[str, Any]:
+        """GET /guild/api/v1/sessions/{sessionId}."""
+        url = (
+            f"{self._config.aiden_url()}/api/v1/sessions/{session_id}"
+            f"{_http.query(self._config.org_id)}"
+        )
+        data = _http.request(url, self._config.api_token)
+        if not isinstance(data, dict):
+            raise StackgenError(f"unexpected get session payload: {data!r}")
+        return data
+
+    def list_session_artifacts(self, session_id: str) -> list[dict[str, Any]]:
+        """GET /guild/api/v1/sessions/{sessionId}/artifacts."""
+        url = (
+            f"{self._config.aiden_url()}/api/v1/sessions/{session_id}/artifacts"
+            f"{_http.query(self._config.org_id)}"
+        )
+        return _http.as_list(_http.request(url, self._config.api_token))
+
+    def download_session_artifact(
+        self,
+        session_id: str,
+        artifact_name: str,
+        output_path: str,
+    ) -> Path:
+        """GET /guild/api/v1/sessions/{sessionId}/artifacts/{name}/download."""
+        encoded = urllib.parse.quote(artifact_name, safe="")
+        url = (
+            f"{self._config.aiden_url()}/api/v1/sessions/{session_id}/artifacts/"
+            f"{encoded}/download{_http.query(self._config.org_id)}"
+        )
+        raw = _http.request(url, self._config.api_token, expect_json=False)
+        dest = Path(output_path)
+        dest.write_bytes(raw)
+        return dest
+
+    def export_session(
+        self,
+        session_id: str,
+        *,
+        parts: str | None = None,
+        format: str = "json",
+    ) -> dict[str, Any]:
+        """GET /guild/api/v1/sessions/{sessionId}/export."""
+        query: dict[str, Any] = {"format": format}
+        if parts:
+            query["parts"] = parts
+        if self._config.org_id:
+            query["orgId"] = self._config.org_id
+        url = (
+            f"{self._config.aiden_url()}/api/v1/sessions/{session_id}/export"
+            f"{_query_string(query)}"
+        )
+        data = _http.request(url, self._config.api_token)
+        if not isinstance(data, dict):
+            raise StackgenError(f"unexpected session export payload: {data!r}")
+        return data
+
+    def terminate_session(self, session_id: str, *, reason: str | None = None) -> dict[str, Any]:
+        """POST /guild/api/v1/sessions/{sessionId}/terminate."""
+        query: dict[str, Any] = {}
+        if self._config.org_id:
+            query["orgId"] = self._config.org_id
+        if reason:
+            query["reason"] = reason
+        url = (
+            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