stackgen-sdk 0.1.8__tar.gz → 0.3.0__tar.gz

{stackgen_sdk-0.1.8 → stackgen_sdk-0.3.0}/.gitignore

@@ -6,6 +6,7 @@ __pycache__/
 dist/
 build/
 .venv/
+.venv-sync/
 venv/
 .venv/**
 .pytest_cache/
@@ -40,3 +41,4 @@ docs/vendor/
 
 # hatch-vcs generated version module (written at build time)
 clients/python/src/stackgen/_version.py
+.venv-sync/

{stackgen_sdk-0.1.8 → stackgen_sdk-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: stackgen-sdk
-Version: 0.1.8
+Version: 0.3.0
 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.1.8 → stackgen_sdk-0.3.0}/src/stackgen/__init__.py

@@ -18,6 +18,7 @@ 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.steer import is_steer_response
 from stackgen.aiden.workflow_builder import (
     AgentDefinition,
     StageDefinition,
@@ -44,6 +45,7 @@ __all__ = [
     "create_agent",
     "create_stage",
     "create_workflow",
+    "is_steer_response",
 ]
 
 

{stackgen_sdk-0.1.8 → stackgen_sdk-0.3.0}/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.8'
-__version_tuple__ = version_tuple = (0, 1, 8)
+__version__ = version = '0.3.0'
+__version_tuple__ = version_tuple = (0, 3, 0)
 
 __commit_id__ = commit_id = None

{stackgen_sdk-0.1.8 → stackgen_sdk-0.3.0}/src/stackgen/aiden/__init__.py

@@ -3,6 +3,7 @@
 from stackgen.aiden.ask import AskArtifactResult
 from stackgen.aiden.namespace import AidenNamespace
 from stackgen.aiden.run_status import ExecutionStatus, RunPhase, RunStatus
+from stackgen.aiden.steer import is_steer_response
 from stackgen.aiden.webhook import WebhookReportResult
 from stackgen.aiden.workflow_builder import (
     AgentDefinition,
@@ -30,4 +31,5 @@ __all__ = [
     "create_agent",
     "create_stage",
     "create_workflow",
+    "is_steer_response",
 ]

{stackgen_sdk-0.1.8 → stackgen_sdk-0.3.0}/src/stackgen/aiden/namespace.py

@@ -7,7 +7,9 @@ from typing import Any
 
 from stackgen.aiden.ask import AskArtifactJourney, AskArtifactResult
 from stackgen.aiden.models import ModelRegistry
+from stackgen.aiden.resources import AidenResources
 from stackgen.aiden.run_status import RunStatus, build_run_status, require_run_ids
+from stackgen.aiden.subscribe import ExecutionSubscribe, SubscribeCompleteResult
 from stackgen.aiden.webhook import WebhookReportJourney, WebhookReportResult
 from stackgen.aiden.webhook_ops import WebhookOps
 from stackgen.aiden.workflow_builder import AgentDefinition, WorkflowDefinition
@@ -25,6 +27,8 @@ class AidenNamespace:
         self._ask = AskArtifactJourney(config)
         self._workflows = WorkflowPublishJourney(config)
         self._webhook_ops = WebhookOps(config)
+        self._resources = AidenResources(config)
+        self._subscribe = ExecutionSubscribe(config)
         self.models = ModelRegistry(config)
 
     def run_webhook_and_download_report(
@@ -229,6 +233,12 @@ class AidenNamespace:
         """
         return self._ask.wait_for_execution(trace_id)
 
+    def wait_for_subscribe_complete(
+        self, trace_id: str, *, timeout_ms: int = 10 * 60 * 1000
+    ) -> SubscribeCompleteResult:
+        """GET SSE /guild/api/v1/executions/{traceId}/subscribe until complete."""
+        return self._subscribe.wait_for_complete(trace_id, timeout_ms=timeout_ms)
+
     def publish_workflow(
         self,
         workflow: WorkflowDefinition,
@@ -241,3 +251,176 @@ class AidenNamespace:
         Pass a committed builder from ``create_workflow(...).then(...).commit()``.
         """
         return self._workflows.publish(workflow, agents=agents, approve=approve)
+
+    # Expanded allowlisted surface (thin REST) — delegated to AidenResources.
+    def get_agent(self, name: str) -> dict[str, Any]:
+        return self._resources.get_agent(name)
+
+    def deregister_agent(self, name: str) -> dict[str, Any]:
+        return self._resources.deregister_agent(name)
+
+    def get_agent_health(self, name: str) -> dict[str, Any]:
+        return self._resources.get_agent_health(name)
+
+    def create_webhook(self, body: dict[str, Any]) -> dict[str, Any]:
+        return self._resources.create_webhook(body)
+
+    def get_webhook(self, webhook_id: str) -> dict[str, Any]:
+        return self._resources.get_webhook(webhook_id)
+
+    def delete_webhook(self, webhook_id: str) -> dict[str, Any]:
+        return self._resources.delete_webhook(webhook_id)
+
+    def create_schedule(self, body: dict[str, Any]) -> dict[str, Any]:
+        return self._resources.create_schedule(body)
+
+    def trigger_schedule(self, schedule_id: str) -> dict[str, Any]:
+        return self._resources.trigger_schedule(schedule_id)
+
+    def list_schedule_runs(self, schedule_id: str) -> list[dict[str, Any]]:
+        return self._resources.list_schedule_runs(schedule_id)
+
+    def delete_schedule(self, schedule_id: str) -> dict[str, Any]:
+        return self._resources.delete_schedule(schedule_id)
+
+    def list_integrations(self) -> list[dict[str, Any]]:
+        return self._resources.list_integrations()
+
+    def list_integration_types(self) -> list[dict[str, Any]]:
+        return self._resources.list_integration_types()
+
+    def get_integration(self, name: str) -> dict[str, Any]:
+        return self._resources.get_integration(name)
+
+    def upsert_integration(self, name: str, body: dict[str, Any]) -> dict[str, Any]:
+        return self._resources.upsert_integration(name, body)
+
+    def delete_integration(self, name: str) -> dict[str, Any]:
+        return self._resources.delete_integration(name)
+
+    def test_integration_connection(self, name: str) -> dict[str, Any]:
+        return self._resources.test_integration_connection(name)
+
+    def refresh_integration_tools(self, name: str) -> dict[str, Any]:
+        return self._resources.refresh_integration_tools(name)
+
+    def list_approvals(self, **params: Any) -> list[dict[str, Any]]:
+        return self._resources.list_approvals(**params)
+
+    def resolve_approval(self, approval_id: str, body: dict[str, Any]) -> dict[str, Any]:
+        return self._resources.resolve_approval(approval_id, body)
+
+    def create_policy(self, body: dict[str, Any]) -> dict[str, Any]:
+        return self._resources.create_policy(body)
+
+    def attach_policy(self, agent_name: str, body: dict[str, Any]) -> dict[str, Any]:
+        return self._resources.attach_policy(agent_name, body)
+
+    def detach_policy(self, agent_name: str, policy_id: str) -> dict[str, Any]:
+        return self._resources.detach_policy(agent_name, policy_id)
+
+    def delete_policy(self, policy_id: str) -> dict[str, Any]:
+        return self._resources.delete_policy(policy_id)
+
+    def evaluate_policy(self, body: dict[str, Any]) -> dict[str, Any]:
+        return self._resources.evaluate_policy(body)
+
+    def list_audit_events(self, **params: Any) -> list[dict[str, Any]]:
+        return self._resources.list_audit_events(**params)
+
+    def get_audit_event(self, event_id: str) -> dict[str, Any]:
+        return self._resources.get_audit_event(event_id)
+
+    def list_audit_facets(self, **params: Any) -> dict[str, Any]:
+        return self._resources.list_audit_facets(**params)
+
+    def list_models(self) -> list[dict[str, Any]]:
+        return self._resources.list_models()
+
+    def list_tools(self, **params: Any) -> list[dict[str, Any]]:
+        return self._resources.list_tools(**params)
+
+    def start_agent_chat(self, agent_name: str, body: dict[str, Any]) -> dict[str, Any]:
+        return self._resources.start_agent_chat(agent_name, body)
+
+    def list_chat_subscriptions(self, **params: Any) -> list[dict[str, Any]]:
+        return self._resources.list_chat_subscriptions(**params)
+
+    def create_chat_subscription(self, body: dict[str, Any]) -> dict[str, Any]:
+        return self._resources.create_chat_subscription(body)
+
+    def get_chat_subscription(self, subscription_id: str) -> dict[str, Any]:
+        return self._resources.get_chat_subscription(subscription_id)
+
+    def update_chat_subscription(
+        self, subscription_id: str, body: dict[str, Any]
+    ) -> dict[str, Any]:
+        return self._resources.update_chat_subscription(subscription_id, body)
+
+    def delete_chat_subscription(self, subscription_id: str) -> dict[str, Any]:
+        return self._resources.delete_chat_subscription(subscription_id)
+
+    def toggle_chat_subscription(
+        self, subscription_id: str, body: dict[str, Any]
+    ) -> dict[str, Any]:
+        return self._resources.toggle_chat_subscription(subscription_id, body)
+
+    def fork_session(
+        self, session_id: str, body: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        return self._resources.fork_session(session_id, body)
+
+    def list_execution_tool_calls(
+        self, trace_id: str, **params: Any
+    ) -> list[dict[str, Any]]:
+        return self._resources.list_execution_tool_calls(trace_id, **params)
+
+    def delete_workflow(self, name: str) -> dict[str, Any]:
+        return self._resources.delete_workflow(name)
+
+    def run_workflow(
+        self, name: str, body: dict[str, Any] | None = None
+    ) -> dict[str, Any]:
+        return self._resources.run_workflow(name, body)
+
+    def create_knowledge_base(self, body: dict[str, Any]) -> dict[str, Any]:
+        return self._resources.create_knowledge_base(body)
+
+    def delete_knowledge_base(self, knowledge_base_id: str) -> dict[str, Any]:
+        return self._resources.delete_knowledge_base(knowledge_base_id)
+
+    def create_knowledge_document(self, body: dict[str, Any]) -> dict[str, Any]:
+        return self._resources.create_knowledge_document(body)
+
+    def get_knowledge_document(self, document_id: str) -> dict[str, Any]:
+        return self._resources.get_knowledge_document(document_id)
+
+    def list_knowledge_documents(self, **params: Any) -> list[dict[str, Any]]:
+        return self._resources.list_knowledge_documents(**params)
+
+    def delete_knowledge_document(self, document_id: str) -> dict[str, Any]:
+        return self._resources.delete_knowledge_document(document_id)
+
+    def list_knowledge_items(self, **params: Any) -> list[dict[str, Any]]:
+        return self._resources.list_knowledge_items(**params)
+
+    def create_skill(self, body: dict[str, Any]) -> dict[str, Any]:
+        return self._resources.create_skill(body)
+
+    def delete_skill(self, skill_id: str) -> dict[str, Any]:
+        return self._resources.delete_skill(skill_id)
+
+    def create_remote_runner(self, body: dict[str, Any]) -> dict[str, Any]:
+        return self._resources.create_remote_runner(body)
+
+    def get_remote_runner(self, runner_id: str) -> dict[str, Any]:
+        return self._resources.get_remote_runner(runner_id)
+
+    def list_remote_runners(self, **params: Any) -> list[dict[str, Any]]:
+        return self._resources.list_remote_runners(**params)
+
+    def list_remote_runner_tasks(self, runner_id: str) -> list[dict[str, Any]]:
+        return self._resources.list_remote_runner_tasks(runner_id)
+
+    def revoke_remote_runner(self, runner_id: str) -> dict[str, Any]:
+        return self._resources.revoke_remote_runner(runner_id)

stackgen_sdk-0.3.0/src/stackgen/aiden/resources.py

@@ -0,0 +1,291 @@
+"""Thin allowlisted Aiden REST helpers beyond webhook/Ask journeys."""
+
+from __future__ import annotations
+
+import json
+import urllib.parse
+from typing import Any
+
+from stackgen import _http
+from stackgen.config import StackgenConfig
+from stackgen.errors import StackgenError
+
+
+def _with_org(config: StackgenConfig, params: dict[str, Any] | None = None) -> dict[str, Any]:
+    query = dict(params or {})
+    if config.org_id and "orgId" not in query:
+        query["orgId"] = config.org_id
+    return query
+
+
+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)
+
+
+def _as_object(data: Any, label: str) -> dict[str, Any]:
+    if not isinstance(data, dict):
+        raise StackgenError(f"unexpected {label}: {data!r}")
+    return data
+
+
+class AidenResources:
+    def __init__(self, config: StackgenConfig) -> None:
+        self._config = config
+
+    def _url(self, path: str, params: dict[str, Any] | None = None) -> str:
+        return (
+            f"{self._config.aiden_url()}/api/v1{path}"
+            + _query_string(_with_org(self._config, params))
+        )
+
+    def _get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        return _http.request(self._url(path, params), self._config.api_token)
+
+    def _send(
+        self,
+        path: str,
+        method: str,
+        body: Any | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> Any:
+        kwargs: dict[str, Any] = {"method": method}
+        if body is not None:
+            kwargs["body"] = json.dumps(body).encode("utf-8")
+            kwargs["content_type"] = "application/json"
+        return _http.request(self._url(path, params), self._config.api_token, **kwargs)
+
+    def get_agent(self, name: str) -> dict[str, Any]:
+        return _as_object(self._get(f"/agents/{name}"), "getAgent")
+
+    def deregister_agent(self, name: str) -> dict[str, Any]:
+        return _as_object(self._send(f"/agents/{name}", "DELETE"), "deregisterAgent")
+
+    def get_agent_health(self, name: str) -> dict[str, Any]:
+        return _as_object(self._get(f"/agents/{name}/health"), "getAgentHealth")
+
+    def create_webhook(self, body: dict[str, Any]) -> dict[str, Any]:
+        return _as_object(self._send("/webhooks", "POST", body), "createWebhook")
+
+    def get_webhook(self, webhook_id: str) -> dict[str, Any]:
+        return _as_object(self._get(f"/webhooks/{webhook_id}"), "getWebhook")
+
+    def delete_webhook(self, webhook_id: str) -> dict[str, Any]:
+        return _as_object(self._send(f"/webhooks/{webhook_id}", "DELETE"), "deleteWebhook")
+
+    def create_schedule(self, body: dict[str, Any]) -> dict[str, Any]:
+        return _as_object(self._send("/schedules", "POST", body), "createSchedule")
+
+    def trigger_schedule(self, schedule_id: str) -> dict[str, Any]:
+        return _as_object(
+            self._send(f"/schedules/{schedule_id}/trigger", "POST", {}),
+            "triggerSchedule",
+        )
+
+    def list_schedule_runs(self, schedule_id: str) -> list[dict[str, Any]]:
+        return _http.as_list(self._get(f"/schedules/{schedule_id}/runs"))
+
+    def delete_schedule(self, schedule_id: str) -> dict[str, Any]:
+        return _as_object(
+            self._send(f"/schedules/{schedule_id}", "DELETE"), "deleteSchedule"
+        )
+
+    def list_integrations(self) -> list[dict[str, Any]]:
+        return _http.as_list(self._get("/integrations"))
+
+    def list_integration_types(self) -> list[dict[str, Any]]:
+        return _http.as_list(self._get("/integrations/types"))
+
+    def get_integration(self, name: str) -> dict[str, Any]:
+        return _as_object(self._get(f"/integrations/{name}"), "getIntegration")
+
+    def upsert_integration(self, name: str, body: dict[str, Any]) -> dict[str, Any]:
+        return _as_object(
+            self._send(f"/integrations/{name}", "PUT", body), "upsertIntegration"
+        )
+
+    def delete_integration(self, name: str) -> dict[str, Any]:
+        return _as_object(
+            self._send(f"/integrations/{name}", "DELETE"), "deleteIntegration"
+        )
+
+    def test_integration_connection(self, name: str) -> dict[str, Any]:
+        return _as_object(
+            self._send(f"/integrations/{name}/test", "POST", {}),
+            "testIntegrationConnection",
+        )
+
+    def refresh_integration_tools(self, name: str) -> dict[str, Any]:
+        return _as_object(
+            self._send(f"/integrations/{name}/refresh-tools", "POST", {}),
+            "refreshIntegrationTools",
+        )
+
+    def list_approvals(self, **params: Any) -> list[dict[str, Any]]:
+        return _http.as_list(self._get("/approvals", params))
+
+    def resolve_approval(self, approval_id: str, body: dict[str, Any]) -> dict[str, Any]:
+        return _as_object(
+            self._send(f"/approvals/{approval_id}", "POST", body), "resolveApproval"
+        )
+
+    def create_policy(self, body: dict[str, Any]) -> dict[str, Any]:
+        return _as_object(self._send("/policies", "POST", body), "createPolicy")
+
+    def attach_policy(self, agent_name: str, body: dict[str, Any]) -> dict[str, Any]:
+        return _as_object(
+            self._send(f"/agents/{agent_name}/policies", "POST", body), "attachPolicy"
+        )
+
+    def detach_policy(self, agent_name: str, policy_id: str) -> dict[str, Any]:
+        return _as_object(
+            self._send(f"/agents/{agent_name}/policies/{policy_id}", "DELETE"),
+            "detachPolicy",
+        )
+
+    def delete_policy(self, policy_id: str) -> dict[str, Any]:
+        return _as_object(self._send(f"/policies/{policy_id}", "DELETE"), "deletePolicy")
+
+    def evaluate_policy(self, body: dict[str, Any]) -> dict[str, Any]:
+        return _as_object(self._send("/policies/evaluate", "POST", body), "evaluatePolicy")
+
+    def list_audit_events(self, **params: Any) -> list[dict[str, Any]]:
+        return _http.as_list(self._get("/audit/events", params))
+
+    def get_audit_event(self, event_id: str) -> dict[str, Any]:
+        return _as_object(self._get(f"/audit/events/{event_id}"), "getAuditEvent")
+
+    def list_audit_facets(self, **params: Any) -> dict[str, Any]:
+        return _as_object(self._get("/audit/facets", params), "listAuditFacets")
+
+    def list_models(self) -> list[dict[str, Any]]:
+        return _http.as_list(self._get("/models"))
+
+    def list_tools(self, **params: Any) -> list[dict[str, Any]]:
+        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(
+            self._send(f"/agents/{agent_name}/chat/start", "POST", body),
+            "startAgentChat",
+        )
+
+    def list_chat_subscriptions(self, **params: Any) -> list[dict[str, Any]]:
+        return _http.as_list(self._get("/platforms/chat/subscriptions", params))
+
+    def create_chat_subscription(self, body: dict[str, Any]) -> dict[str, Any]:
+        return _as_object(
+            self._send("/platforms/chat/subscriptions", "POST", body),
+            "createChatSubscription",
+        )
+
+    def get_chat_subscription(self, subscription_id: str) -> dict[str, Any]:
+        return _as_object(
+            self._get(f"/platforms/chat/subscriptions/{subscription_id}"),
+            "getChatSubscription",
+        )
+
+    def update_chat_subscription(
+        self, subscription_id: str, body: dict[str, Any]
+    ) -> dict[str, Any]:
+        return _as_object(
+            self._send(f"/platforms/chat/subscriptions/{subscription_id}", "PUT", body),
+            "updateChatSubscription",
+        )
+
+    def delete_chat_subscription(self, subscription_id: str) -> dict[str, Any]:
+        return _as_object(
+            self._send(f"/platforms/chat/subscriptions/{subscription_id}", "DELETE"),
+            "deleteChatSubscription",
+        )
+
+    def toggle_chat_subscription(
+        self, subscription_id: str, body: dict[str, Any]
+    ) -> dict[str, Any]:
+        return _as_object(
+            self._send(
+                f"/platforms/chat/subscriptions/{subscription_id}/toggle",
+                "POST",
+                body,
+            ),
+            "toggleChatSubscription",
+        )
+
+    def fork_session(self, session_id: str, body: dict[str, Any] | None = None) -> dict[str, Any]:
+        return _as_object(
+            self._send(f"/sessions/{session_id}/fork", "POST", body or {}),
+            "forkSession",
+        )
+
+    def list_execution_tool_calls(
+        self, trace_id: str, **params: Any
+    ) -> list[dict[str, Any]]:
+        return _http.as_list(self._get(f"/executions/{trace_id}/tool-calls", params))
+
+    def delete_workflow(self, name: str) -> dict[str, Any]:
+        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(
+            self._send(f"/workflows/{name}/run", "POST", body or {}), "runWorkflow"
+        )
+
+    def create_knowledge_base(self, body: dict[str, Any]) -> dict[str, Any]:
+        return _as_object(
+            self._send("/knowledge/bases", "POST", body), "createKnowledgeBase"
+        )
+
+    def delete_knowledge_base(self, knowledge_base_id: str) -> dict[str, Any]:
+        return _as_object(
+            self._send(f"/knowledge/bases/{knowledge_base_id}", "DELETE"),
+            "deleteKnowledgeBase",
+        )
+
+    def create_knowledge_document(self, body: dict[str, Any]) -> dict[str, Any]:
+        return _as_object(
+            self._send("/knowledge/documents", "POST", body), "createKnowledgeDocument"
+        )
+
+    def get_knowledge_document(self, document_id: str) -> dict[str, Any]:
+        return _as_object(
+            self._get(f"/knowledge/documents/{document_id}"), "getKnowledgeDocument"
+        )
+
+    def list_knowledge_documents(self, **params: Any) -> list[dict[str, Any]]:
+        return _http.as_list(self._get("/knowledge/documents", params))
+
+    def delete_knowledge_document(self, document_id: str) -> dict[str, Any]:
+        return _as_object(
+            self._send(f"/knowledge/documents/{document_id}", "DELETE"),
+            "deleteKnowledgeDocument",
+        )
+
+    def list_knowledge_items(self, **params: Any) -> list[dict[str, Any]]:
+        return _http.as_list(self._get("/knowledge/items", params))
+
+    def create_skill(self, body: dict[str, Any]) -> dict[str, Any]:
+        return _as_object(self._send("/skills", "POST", body), "createSkill")
+
+    def delete_skill(self, skill_id: str) -> dict[str, Any]:
+        return _as_object(self._send(f"/skills/{skill_id}", "DELETE"), "deleteSkill")
+
+    def create_remote_runner(self, body: dict[str, Any]) -> dict[str, Any]:
+        return _as_object(
+            self._send("/remote-runners", "POST", body), "createRemoteRunner"
+        )
+
+    def get_remote_runner(self, runner_id: str) -> dict[str, Any]:
+        return _as_object(self._get(f"/remote-runners/{runner_id}"), "getRemoteRunner")
+
+    def list_remote_runners(self, **params: Any) -> list[dict[str, Any]]:
+        return _http.as_list(self._get("/remote-runners", params))
+
+    def list_remote_runner_tasks(self, runner_id: str) -> list[dict[str, Any]]:
+        return _http.as_list(self._get(f"/remote-runners/{runner_id}/tasks"))
+
+    def revoke_remote_runner(self, runner_id: str) -> dict[str, Any]:
+        return _as_object(
+            self._send(f"/remote-runners/{runner_id}", "DELETE"), "revokeRemoteRunner"
+        )

stackgen_sdk-0.3.0/src/stackgen/aiden/steer.py

@@ -0,0 +1,19 @@
+"""Helpers for mid-turn Ask Guild steering responses."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from stackgen import _http
+
+
+def is_steer_response(body: Any) -> bool:
+    """True when Ask Guild reports a running turn absorbed the message.
+
+    Check this on the dict returned by ``client.aiden.start_ask(...)`` after a
+    mid-session follow-up. When true, ``trace_id`` names the running turn and no
+    new turn was started.
+    """
+    if not isinstance(body, dict):
+        return False
+    return _http.text(body.get("action")).lower() == "steer"

stackgen_sdk-0.3.0/src/stackgen/aiden/subscribe.py

@@ -0,0 +1,87 @@
+"""SSE subscribeExecution helper."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+from stackgen import _http
+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:
+        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
+                            return SubscribeCompleteResult(
+                                ok=True,
+                                event_count=event_count,
+                                raw_snippet="\n---\n".join(chunks[-5:]),
+                            )
+                        if "subscribe_end" in lower and "error" not in lower:
+                            ok = True
+        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
+
+        return SubscribeCompleteResult(
+            ok=ok,
+            event_count=event_count,
+            raw_snippet="\n---\n".join(chunks[-5:]),
+        )