Changelog

Newest first. The same version number is published on PyPI and npm as stackgen-sdk. Pin that version in CI or production.

Write each bullet for the person installing the SDK: what they can do now, when they would use it, and a sample link when one exists. Skip internal ticket IDs, codegen notes, and allowlist mechanics.

Release candidates for an upcoming version share that version’s section. Preview install: pip install stackgen-sdk==X.Y.ZrcN or npm install stackgen-sdk@next.

0.5.0

• Use the names you see in the StackGen UI. Configure the workspace with workspace_id / workspaceId / WorkspaceID or STACKGEN_WORKSPACE_ID, manage workspaces through client.workspaces / client.Workspaces, create knowledge hubs with create_knowledge_hub / createKnowledgeHub, and manage LLM providers and models through client.aiden.llm (Go: Aiden.DeleteLLMProvider). Your existing code keeps working: org_id, STACKGEN_PROJECT, client.orgs, create_knowledge_base and aiden.models are deprecated aliases until the next major version. Python warns with DeprecationWarning; TypeScript and Go mark them deprecated for your editor and linter. Old → new table and how to silence the warnings: Renamed in 0.5.0.
• Catch a mixed-up workspace before it calls the API. Setting the new and the old workspace option (or STACKGEN_WORKSPACE_ID and STACKGEN_PROJECT) to different values now fails at config time instead of silently picking one.
• Filter knowledge documents by knowledge hub. Pass knowledge_hub_id to list_knowledge_documents, list_knowledge_items and create_knowledge_document; responses include knowledge_hub_id next to knowledge_base_id.
• Run the samples with the new flag. Examples take --workspace-id and read STACKGEN_WORKSPACE_ID; --org-id and STACKGEN_PROJECT still work.

• Change how often a connector schedule runs. setConnectorScheduleInterval(scheduleId, everySeconds), Python set_connector_schedule_interval, and Go SetConnectorScheduleInterval PUT /connectors/schedules/{schedule_id}/interval. The schedule keeps its paused state and any running sync; the next run is one new interval from now, rounded up to the next whole minute. everySeconds must be at least 60. Sample: Context Graph inventory.

• Approve a workflow draft without re-publishing. getWorkflow / createWorkflow / approveWorkflowVersion (and Python / Go twins) expose the steps publishWorkflow already uses. Read an execution flight record with getExecutionFlightRecord(traceId) for post-run timelines.
• Search Context Graph tools with a plain query. searchGraphTools("dashboard"), Python search_graph_tools, and Go SearchGraphToolsQuery take a query string or a full request body. getRecord also accepts optional query params such as include_facets. Sample: Context Graph inventory.
• Ask Context Graph something more useful than “is it up.” getWorkspaceStatus / get_workspace_status / GetWorkspaceStatus combine readiness, per-type record counts, and each connector source’s last sync outcome into one call. health / ready stay intentionally minimal (liveness/readiness probes that must not leak internal detail); use the new helper when you want to know whether the workspace graph actually has data and whether the last sync succeeded. Sample: Context Graph inventory.

0.4.0

• Import typed models and enums from the SDK. Use Investigation, AlertV1, RegisteredModel, AgentInfo, GuildIntegration, IngestedDocument, VersionStatus, DocumentProcessingStatus, ReasoningEffortSetting, MeResponse, AppStack, and IacType from stackgen-sdk (TypeScript and Python) or clients/go/models (Go) instead of generated OpenAPI clients. Facade returns for getAgent / listModels / listIntegrations / getKnowledgeDocument / getInvestigation / listAlerts / orgs.me / orgs.getAppStack are narrowed to those shapes. Wire JSON stays snake_case for Aiden/SRE and camelCase for AppCD me / AppStacks.
• Query the Context Graph from the SDK. client.contextGraph (Python context_graph, Go ContextGraph) covers health/ready, record types and queries, schema, connectors and syncs (including syncAndWait / sync_and_wait), entity link rules, and graph tool search. Default base is ${STACKGEN_URL}/context-graph; set contextGraphUrl / context_graph_url / ContextGraphURL for local or port-forward runs. Sample: Context Graph inventory.
• Approve a workflow one step at a time. aiden.getWorkflow, createWorkflow (REST create), and approveWorkflowVersion expose the individual draft/approve calls already used inside publishWorkflow. getExecutionFlightRecord returns the unified flight-record timeline for a trace (same payload as the Guild flight recorder UI).
• Manage org membership from the SDK. orgs.assignUsers, removeUser, and listRoles cover AppCD membership; orgs.me returns a typed MeResponse for the calling token.

• Drive the SRE inbox beyond pull + investigate. sre.setupStatus, clusterHealth, supportedActions, alertWebhook, alertSchedule, ingestAlerts, plus discovery helpers (startDiscovery, getDiscovery, listDiscoveries, waitForDiscovery, listDiscoveredEntities) cover the weekly SRE app journey.

• Create a blank AppStack without picking a cloud. orgs.create_app_stack / createAppStack / CreateAppStack set coreConfig.provider to aws when the payload has no cloud provider, so { name, components: [] } can finish IaC generation instead of failing IAC_GEN_INVALID_OPTIONS. Pass gcp, azure, civo, oci, or other in coreConfig.provider for another cloud. get_app_stack / list_app_stacks / delete_app_stacks (and the TypeScript / Go twins) cover the rest of the round trip.
• List policies in a project. aiden.listPolicies returns the project’s policies. Optional filters are type, tag, limit, and offset.
• Ride out CloudFront 502s on every call. Python and TypeScript now retry gateway 502/503/504 and transport errors for POST and PATCH as well as GET (same wall-clock budget as before). Go clients use hashicorp/go-retryablehttp by default with a replayable request body, so fixture creates and approves survive short edge blips. Pass retry_gateway_outage=False / retryGatewayOutage: false when you need the old fail-fast POST behavior. Application 500 on POST still fails immediately.
• POST/PATCH gateway outages fail closed after 3 attempts in createRetryFetch. The “ride out CloudFront 502s on every call” change also moved non-idempotent calls onto the wall-clock budget, so a persistent edge outage long-retried MCP dial and JSON-RPC POSTs for the whole budget (and budgetMs: 0 stripped their retries entirely). createRetryFetch now keeps POST/PATCH on the short attempt budget (3 attempts) regardless of budgetMs; idempotent methods keep the wall-clock budget. request() is unchanged (pass retryGatewayOutage: false there for fail-fast POSTs).
• Watch an agent reply in real time. streamExecutionEvents / stream_execution_events yields reply text and tool calls as Aiden runs, so you can build a chat UI without polling. Pair it with startAgentChat / startAsk / runWorkflow, then stop on RUN_FINISHED or abort the TypeScript signal. Sample: Stream agent chat.
• Fill an agent or workflow picker. listAgents / list_agents and listWorkflows / list_workflows return the names a desktop or editor host needs. System agents such as aiden-router still accept startAgentChat even when they are absent from the list. Sample: Stream agent chat.
• Inject your own fetch (TypeScript). Pass fetch on StackgenConfig so Tauri or a browser host can route HTTP and SSE through its transport without patching globalThis.fetch.
• Pull fresh alerts on demand. pull_alerts / pullAlerts / PullAlerts starts an SRE inbox refresh (and joins a pull that is already running). pull_alerts_and_wait / pullAlertsAndWait / PullAlertsAndWait blocks until the counts for created, updated, and resolved alerts are ready. Sample: Pull alerts.
• Start an investigation and get the RCA in one call. investigate_alert_and_wait / investigateAlertAndWait / InvestigateAlertAndWait starts from an alert id and returns when status is completed, draft, or resolved (raises on failed or cancelled). Sample: Investigate alert.
• Triage alerts and close investigation threads from code. ignore_alert, set_alert_attention, list_investigation_groups, resolve_investigations, cancel_investigations, fork_investigation, and list_remediation_checks (and the TypeScript / Go twins) cover the operator inbox after the RCA lands. Sample: Triage alerts.
• Pull tickets into the Ops Inbox. sync_requests / syncRequests / SyncRequests refreshes Linear, Jira, or ServiceNow tickets. fetch_request / fetchAndWait imports one ticket key and waits for triage. Sample: Sync Ops Inbox.
• Approve a request and wait for the run. approve_and_wait / approveAndWait / ApproveAndWait starts fulfillment and returns when execution_status is terminal. post_source_comment writes back to the upstream ticket. Sample: Approve request.
• Find workflows from recent tickets. start_workflow_discovery and wait_for_workflow_discovery (and the TypeScript / Go twins) analyze ticket history until classes are ready. Sample: Discover workflows.
• Send chat files, not just text. startAgentChatWithFiles (TypeScript), start_agent_chat_with_files (Python), and StartAgentChatWithFiles (Go) post a chat turn as multipart/form-data. Once the agent’s reply (or the execution debug ZIP) surfaces an attachment://<session_id>/<attachment_id> handle, pull the file back with downloadSessionAttachment / download_session_attachment / DownloadSessionAttachment, and clear a session’s uploads with deleteSessionAttachments / delete_session_attachments / DeleteSessionAttachments. Sample: Chat session attachments.
• Rename, star, or archive a conversation from code. updateSession / update_session / UpdateSessionMetadata patch only the session fields you pass — useful for labeling a run after the fact or hiding noisy test sessions from the Activity list without deleting them.
• Pre-flight a model before you wire an agent to it. testModel / test_model / TestModel runs a small generation call against a provider and returns {success, message} without registering anything — confirm a rotated API key or a new model id works before switching traffic. Retire old configurations with deleteModel / delete_model / DeleteModel and deleteProvider / delete_provider / DeleteModelProvider. Sample: Test and retire a model.
• Abort-safe gateway retries for custom fetch wrappers (TypeScript). Closing an MCP Streamable HTTP session aborts the long-lived SSE GET. That AbortError is no longer treated as a gateway network outage, so clients do not burn STACKGEN_TRANSIENT_RETRY_BUDGET_MS (or a Nightly 10-minute budget) after close(). Use createRetryFetch({ budgetMs }) for OpenAPI clients and MCP transports; isAbortError is exported for the same check. Bearer request() also rethrows AbortError instead of retrying it as a network blip.
• Long Guild runs finish instead of aborting at the client clock. The TypeScript GuildRunSubscribe deadline is now an inactivity budget: every consumed event and every confirmation poll re-arms it, so a run that keeps streaming progress is never cut off by timeoutMs. Silent streams still abort at the budget.
• Cap how long a Guild run wait may last. TypeScript waitForRunSubscribeComplete takes maxWallClockMs for the whole wait. timeoutMs still resets when events arrive, so a stuck run that keeps sending events never ends on its own. Set maxWallClockMs to the longest you will wait. The call then returns aborted: true and you can stop the session. Omit it and nothing changes.
• Reconnect when a Guild run stream goes quiet. TypeScript waitForRunSubscribeComplete reconnects if no frame arrives for idleTimeoutMs (90s by default) on an open connection, same idea as Ask subscribe waits. Missed frames replay on reconnect. When reconnects run out, the call fails with an idle-stall snippet instead of sitting until the inactivity budget.
• Every code sample tab shows complete code. Python and TypeScript tabs no longer show an empty “Complete script” block. Go snippets that pass EntityRefs or AutoApproveTools show the full slice literal again instead of a bare type, so they compile when you paste them. Investigate an SRE alert from TypeScript with the new examples/sre/investigate-alert.ts. Sample: SRE investigate alert.
• Webhook trigger waits through a gateway drop. trigger_webhook retries HTTP 502, 503, and 504 for about 15 seconds when the edge never delivers the POST to Aiden. A real application error still fails on the first response. Sample: Webhook session artifact.
• Run Ask, webhook, workflow, policy, audit, and SRE journeys from Go. Start an Ask and check it later with GetRunStatus, acknowledge a webhook, download the session report or debug ZIP, publish a workflow, open break-glass, export audit events, and investigate an alert. Pick Go on any code sample page. Existing Go samples retry transient HTTP failures. Sample: Async Ask worker.
• Choose or create an assistant workspace from Go. List accessible workspaces, create one with the token’s caller as admin, and list its agents to build connection pickers without sending credentials to the browser. Sample: code-samples/aiden-chat-backend.
• Build a Grafana assistant with the Go SDK. Start and continue Aiden agent chats, consume text and tool events, resolve individual tool approvals, stop sessions, and manage agent settings and integrations without embedding an LLM client. Context-aware Vault setup keeps credentials server-side. Sample: examples/go/aiden-chat/agent-chat.go.
• Trigger a webhook and download the session report from Go. Aiden.RunWebhookAndDownloadReport mirrors the Python/TypeScript one-call journey (trigger → wait for session → download session-report.md). Step-by-step helpers: TriggerWebhook, WaitForWebhookSession, DownloadSessionArtifact. Samples: examples/go/webhook/ · Webhook → session → artifact. The Go module is invite-only while this repository is private; ask StackGen for GitHub access before go get.

pip install stackgen-sdk==0.4.0
npm install stackgen-sdk@0.4.0
# Go: invite-only (private repo)
go get github.com/appcd-dev/stackgen-sdk/clients/go@v0.4.0

# Preview before GA (example)
# pip install stackgen-sdk==0.4.0rc1
# npm install stackgen-sdk@0.4.0-rc.1
# npm install stackgen-sdk@next

• Ride out gateway rollouts without failing Ask waits. Idempotent Guild calls (GET/HEAD/PUT/DELETE) and session terminate retry HTTP 502/503/504 and network drops for up to two minutes by default (override with STACKGEN_TRANSIENT_RETRY_BUDGET_MS or transientRetryBudgetMs). Subscribe reconnects keep going for that same budget instead of stopping after three drops. Application 500s still fail fast. Use when CI runs against a mothership that redeploys mid-suite.

• Log every Ask/chat/workflow/webhook session id. startAsk, startAgentChat, runWorkflow, and triggerWebhook emit session started kind=… session_id=… trace_id=… at info, and call optional onSessionStarted so operators can copy the ids from CI logs without scraping response bodies.

• Upsert an integration with its secrets in one call. upsert_integration_with_secrets / upsertIntegrationWithSecrets takes a plain secrets map (for example {"token": "…"} or Grafana base_url / api_token). The SDK looks up Vault’s required metadata keys from the integration catalog, stores the secret, binds secret_ref_ids, and creates or updates the integration. Pass vault_category / vault_subcategory (TS: vaultCategory / vaultSubcategory) when you need to override discovery. Use when CI provisions a tool-backed agent from a vendor token. Sample: Integration secrets → agent → Ask.

• Discover Vault secret metadata keys. vault.get_supported_metadata / getSupportedMetadata returns typed VaultSupportedFormat rows (category, subcategory, keys with required/mask/default, optional OAuth hint) from GET /support/metadata. Use it when building custom secret forms or debugging which keys an integration needs.

• Register and update agents with full config. Call register_agent / registerAgent and update_agent / updateAgent with integrations, world_model_enabled, remote_runners, auto-approve / HITL fields, and the rest of the register body so CI can provision agents without raw Guild HTTP. Sample: Integration secrets → agent → Ask.

• Store and delete Vault secrets (granular path). client.vault.store_secret / storeSecret, delete_secret / deleteSecret, plus helpers for github, grafana, kafka, and generic secrets. Pair with upsert_integration / upsertIntegration and explicit secret_ref_ids when you already manage Vault yourself. Sample: Integration secrets → agent → Ask.

• Pin Ask execution mode. Pass mode="plan" or "simple" on start_ask / startAsk (and the run-and-download helper) so the session keeps a Genie pin across turns.

• Read one approval and integrations with tools. get_approval / getApproval fetches a HITL item by id. get_integration / getIntegration defaults to include_tools=true so discovered_tools populate.

• Bound a slow debug ZIP export. Pass timeout_seconds / timeoutMs to download_execution_debug_zip / downloadExecutionDebugZip when a cold Activity export must not hang the caller. The call still writes a validated ZIP to your path when it finishes in time. Sample: Ask → debug ZIP.

• Download every session note in one call. After Ask finishes, download_session_artifacts(session_id, out_dir) / downloadSessionArtifacts(sessionId, outDir) lists metadata, sanitizes filenames, and saves each file. Returns { name, path, meta } rows so CI can keep operator follow-through and Keep a Changelog notes without a hand-rolled loop. Sample: Ask → session artifacts.

• Update a webhook after create. update_webhook / updateWebhook sends PUT /webhooks/{id} so you can change response_status, response_headers, or other mutable fields without deleting the endpoint. Useful when you tighten Linear-style acknowledgements after the first create. Sample: Webhook acknowledgement.

• Skip unrelated webhook deliveries before they cost a run. A GitHub (or any) webhook that fires on every event — PR edits, comments, pings — can now carry a filter_cel condition. Set it on create_webhook / createWebhook or change it with update_webhook / updateWebhook (an explicit empty string clears it). A delivery that does not match gets the usual acknowledgement with no run, no invocation row, and no AI-query charge. Try a condition before saving it with preview_webhook_filter / previewWebhookFilter against a sample payload and headers. Sample: Webhook condition (filter_cel).

• Download the execution debug ZIP for triage. Call client.aiden.download_execution_debug_zip(trace_id, path) (TypeScript: downloadExecutionDebugZip) to save the same Activity / watch bundle operators use (DAG, subscribe replay, optional judge). Sample: Ask → debug ZIP. Live PR CI collects those ZIPs for every sample that produced a session or trace and uploads them as the live-debug-zips artifact.

• Turn on SDK logs when you need them. Set STACKGEN_LOG_LEVEL (or log_level / logLevel on config) to debug, info, warn, or error. Python uses the stdlib stackgen logger; TypeScript uses a leveled console logger. HTTP retries warn, request lines stay at debug, and tokens are redacted. Live CI runs with info.

• Point agents at your tenant Ollama model (opt-in). Call client.aiden.models.list_providers() / resolve_tenant_llm_model() (TypeScript: listProviders / resolveTenantLlmModel), then pass the registered model name into create_agent(..., model_names=[...]) / createAgent({ modelNames: [...] }) so publish skips Guild’s built-in default. Live CI leaves fixture agents on the Guild default unless you set STACKGEN_MODEL_NAME. Sample: use-tenant-llm.py.

• Create and delete a disposable project from the SDK. client.orgs.create / client.orgs.delete (and the TypeScript twins) call the mothership org APIs so CI can stand up an e2e-sdk-… project, run samples, tear down fixtures, then delete the project. Create resolves the token owner via GET /auth/me and adds them as workspace-admin (userAssignments) so the calling user can open the project in the UI. Pass add_caller=False / addCaller: false to skip. Pair with STACKGEN_URL and STACKGEN_TOKEN only; the project id is returned from create.

• Compile and run the shipped samples on every pull request. Python samples are compiled and TypeScript samples are typechecked before merge. Pull requests from this repository also create an e2e-sdk-* project, run the samples in parallel (each case gets its own agent, workflow, webhook, and output dir so one sample cannot mutate another), then delete the project. CI also runs org cleanup under if: always() (and a pre-run sweep) so cancelled jobs cannot leave e2e-sdk-* projects behind. Includes Ask → session artifacts. Forks still get the compile check. Set STACKGEN_URL and STACKGEN_TOKEN as Actions secrets. Empty CI projects point webhook/schedule samples at a published workflow (--workflow); agent targets still need an integration.

• Point webhook ack and schedule+HITL samples at a workflow. Pass --workflow instead of --agent when the project has no agent integrations. Samples: Webhook ack headers, Webhook + schedule + HITL.

• Re-publish an existing agent without a parsing error. publishWorkflow / publish_workflow omit name on the update PUT (name stays in the path). Re-running create-hello against the same agent name works again.

• Toggle chat subscriptions with PUT. toggleChatSubscription / toggle_chat_subscription match Guild’s allowlisted method (was POST, which returned 405). Sample: Chat subscriptions.

• Dry-run a policy with a real agent id. evaluatePolicy / evaluate_policy needs agent.id (from getAgent / get_agent) plus name, timestamp, and tool. Name alone returns HTTP 422. Sample: Policy guardrails and break-glass.

• Download every session note after Ask finishes. Start with start_ask / startAsk, wait on wait_for_subscribe_complete / waitForSubscribeComplete, then list_session_artifacts / listSessionArtifacts and download each file. Use this for operator follow-through notes, Keep a Changelog product notes, and any session that ships more than one artifact. Sample: Ask → session artifacts.

• Keep waiting through a brief platform blip. wait_for_execution / waitForExecution, artifact waits, and wait_for_subscribe_complete / waitForSubscribeComplete retry GET 5xx, 429, and dropped connections inside your existing timeout instead of failing the run on the first HTTP 500 during a rollout. Non-retryable 4xx and real terminal states (failed, error, cancelled) still fail immediately. When the deadline expires on a blip, the timeout names the last status (status=500 or status=network_error). Subscribe helpers also confirm the execution settled after the SSE stream ends.

• Reconnect a dropped subscribe stream, and retry idempotent terminate. wait_for_subscribe_complete / waitForSubscribeComplete reconnect after a plain mid-stream EOF (bounded, one deadline) and retry a reconnect fetch that returns 5xx/429/network. terminate_session / terminateSession retries the same transient statuses with bounded backoff because Guild documents terminate as idempotent. Other POSTs (webhook/workflow starts) still do not auto-retry. The rules live in shared policy helpers (transient / SUBSCRIBE_RECONNECT_MAX / retry_idempotent_op) so callers can reason about what retries and what fails fast.

• Ride out a silently stalled subscribe stream. waitForSubscribeComplete (TypeScript) now reopens the SSE connection when it goes quiet mid-execution — open, but delivering no frames and no EOF (a wedged proxy or half-open connection). After SUBSCRIBE_IDLE_TIMEOUT_MS of silence the pass is treated as dropped and reopened within the same bounded reconnect budget, and the server replays the missed frames, so a long execution no longer needs one unbroken connection to finish. If the budget is exhausted the failure says the stream stalled instead of claiming an EOF.

• Answer Linear (and similar) with the ack they expect. When you create a webhook you can set response_status to 200, 201, or 204 and optional response_headers so the provider gets a fast HTTP acknowledgement while Aiden still starts the agent or app forward in the background. Use this when Linear (or another system) retries or disables the endpoint on 202 Accepted. Omit the fields to keep the platform default (202). Sample: Webhook acknowledgement.

• Override policies in an outage, then put the guardrails back. breakGlass / endBreakGlass take a reason and duration (1–480 minutes). Aiden records who opened the glass from your API token (activated_by on the response; you do not pass an operator name). whenPoliciesDisagree picks the tie-break when several policies conflict (any_deny_blocks is the usual production choice). Create, attach (including shadow), and evaluate Rego as before. Sample: Policy guardrails and break-glass.

• Export your full audit trail, not just the first page. export_audit_events(path, …) / exportAuditEvents(path, …) page past Aiden’s cursor cap and write NDJSON to a file. Pass format: "ocsf" for SIEM or external-auditor hand-off. Use iter_audit_events / iterAuditEvents when you want to stream without writing a file. Sample: Export audit events.

0.3.0

pip install stackgen-sdk==0.3.0
npm install stackgen-sdk@0.3.0

• Keep talking during an investigation. You can send another Ask on the same session while a turn is still running. When the turn takes the message, the reply sets action to steer and you wait on that one trace_id instead of starting a parallel dig. Handy for on-call follow-ups, Slack bots that relay the next human message, and CI that learns more context mid-run. Helpers: isSteerResponse / is_steer_response. Sample: Ask mid-turn steer.
• Route Slack and Teams from code. Create, list, update, silence, and delete chat subscriptions so mentions and alert bots land on the right installed app and channel set. Useful when you stand up on-call channels, mute a route during a load test, or tear down a war-room subscription when the room closes. Sample: Chat subscriptions.

0.2.0

pip install stackgen-sdk==0.2.0
npm install stackgen-sdk@0.2.0

• Kick off Aiden from webhooks and schedules, clear approvals, and wait until the run finishes on the event stream. Sample: Webhook + schedule + HITL.
• Start Ask or webhook work from a queue or CI job without blocking the start call, then poll or wait later in another worker.