getstack 3.0.0__tar.gz → 4.4.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (208) hide show
  1. {getstack-3.0.0 → getstack-4.4.0}/.gitignore +24 -2
  2. getstack-4.4.0/CLAUDE.md +91 -0
  3. {getstack-3.0.0 → getstack-4.4.0}/LICENSE +1 -1
  4. getstack-4.4.0/PKG-INFO +725 -0
  5. getstack-4.4.0/README.md +693 -0
  6. {getstack-3.0.0 → getstack-4.4.0}/pyproject.toml +43 -4
  7. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/__init__.py +507 -173
  8. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/_async/__init__.py +1 -1
  9. getstack-4.4.0/src/getstack/_async/accounts.py +1081 -0
  10. getstack-4.4.0/src/getstack/_async/agent_identity.py +42 -0
  11. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/_async/agents.py +58 -11
  12. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/_async/audit.py +4 -4
  13. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/_async/authority.py +94 -109
  14. getstack-4.4.0/src/getstack/_async/billing.py +32 -0
  15. getstack-4.4.0/src/getstack/_async/brain.py +71 -0
  16. getstack-4.4.0/src/getstack/_async/calendar.py +170 -0
  17. getstack-4.4.0/src/getstack/_async/catalogue.py +38 -0
  18. getstack-4.4.0/src/getstack/_async/chat_channels.py +56 -0
  19. getstack-4.4.0/src/getstack/_async/control_policies.py +114 -0
  20. getstack-4.4.0/src/getstack/_async/control_socket.py +154 -0
  21. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/_async/credentials.py +1 -3
  22. getstack-4.4.0/src/getstack/_async/delivery_methods.py +95 -0
  23. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/_async/detector_config.py +9 -8
  24. getstack-4.4.0/src/getstack/_async/drive.py +277 -0
  25. getstack-4.4.0/src/getstack/_async/dropoffs.py +93 -0
  26. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/_async/evidence_packs.py +6 -8
  27. getstack-4.4.0/src/getstack/_async/flagged_content.py +24 -0
  28. getstack-4.4.0/src/getstack/_async/fleets.py +155 -0
  29. getstack-4.4.0/src/getstack/_async/governance.py +22 -0
  30. getstack-4.4.0/src/getstack/_async/identity.py +184 -0
  31. getstack-4.4.0/src/getstack/_async/inbound_webhooks.py +71 -0
  32. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/_async/intents.py +42 -25
  33. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/_async/llm.py +108 -22
  34. getstack-4.4.0/src/getstack/_async/making.py +189 -0
  35. getstack-4.4.0/src/getstack/_async/meetings.py +162 -0
  36. getstack-4.4.0/src/getstack/_async/memory.py +300 -0
  37. getstack-4.4.0/src/getstack/_async/message_access.py +39 -0
  38. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/_async/missions.py +85 -21
  39. getstack-4.4.0/src/getstack/_async/network.py +220 -0
  40. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/_async/notifications.py +14 -10
  41. getstack-4.4.0/src/getstack/_async/partner_accounts.py +275 -0
  42. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/_async/passport_session.py +1 -1
  43. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/_async/passports.py +64 -58
  44. getstack-4.4.0/src/getstack/_async/payments.py +127 -0
  45. getstack-4.4.0/src/getstack/_async/pii_config.py +24 -0
  46. getstack-4.4.0/src/getstack/_async/post.py +221 -0
  47. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/_async/proxy.py +64 -10
  48. getstack-4.4.0/src/getstack/_async/rentahuman.py +115 -0
  49. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/_async/reviews.py +1 -1
  50. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/_async/scan.py +10 -7
  51. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/_async/security_events.py +5 -7
  52. getstack-4.4.0/src/getstack/_async/services.py +171 -0
  53. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/_async/skills.py +29 -25
  54. getstack-4.4.0/src/getstack/_async/team.py +57 -0
  55. getstack-4.4.0/src/getstack/_async/trust.py +37 -0
  56. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/_async/usage.py +4 -4
  57. getstack-4.4.0/src/getstack/_async/wake.py +123 -0
  58. getstack-4.4.0/src/getstack/_async/website.py +130 -0
  59. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/_authority_request.py +1 -2
  60. getstack-4.4.0/src/getstack/_control_ref.py +42 -0
  61. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/_fleet_key.py +6 -3
  62. getstack-4.4.0/src/getstack/accounts.py +1326 -0
  63. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/agent_auth.py +55 -38
  64. getstack-4.4.0/src/getstack/agent_identity.py +91 -0
  65. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/agents.py +84 -15
  66. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/audit.py +10 -5
  67. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/auth.py +72 -11
  68. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/authority.py +57 -82
  69. getstack-4.4.0/src/getstack/billing.py +67 -0
  70. getstack-4.4.0/src/getstack/brain.py +138 -0
  71. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/browser_bootstrap.py +43 -30
  72. getstack-4.4.0/src/getstack/calendar.py +265 -0
  73. getstack-4.4.0/src/getstack/catalogue.py +97 -0
  74. getstack-4.4.0/src/getstack/chat_channels.py +77 -0
  75. getstack-4.4.0/src/getstack/client.py +542 -0
  76. getstack-4.4.0/src/getstack/control_policies.py +266 -0
  77. getstack-4.4.0/src/getstack/control_server.py +220 -0
  78. getstack-4.4.0/src/getstack/control_socket.py +259 -0
  79. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/credentials.py +0 -1
  80. getstack-4.4.0/src/getstack/delivery_methods.py +92 -0
  81. getstack-4.4.0/src/getstack/detector_config.py +50 -0
  82. getstack-4.4.0/src/getstack/drive.py +555 -0
  83. getstack-4.4.0/src/getstack/dropoffs.py +102 -0
  84. getstack-4.4.0/src/getstack/errors.py +632 -0
  85. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/evidence_packs.py +8 -9
  86. getstack-4.4.0/src/getstack/flagged_content.py +46 -0
  87. getstack-4.4.0/src/getstack/fleets.py +149 -0
  88. getstack-4.4.0/src/getstack/governance.py +48 -0
  89. getstack-4.4.0/src/getstack/identity.py +217 -0
  90. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/inbound_webhooks.py +36 -13
  91. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/intents.py +55 -38
  92. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/llm.py +143 -25
  93. getstack-4.4.0/src/getstack/making.py +197 -0
  94. getstack-4.4.0/src/getstack/meetings.py +235 -0
  95. getstack-4.4.0/src/getstack/memory.py +508 -0
  96. getstack-4.4.0/src/getstack/message_access.py +65 -0
  97. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/missions.py +125 -28
  98. getstack-4.4.0/src/getstack/network.py +322 -0
  99. getstack-4.4.0/src/getstack/network_install.py +233 -0
  100. getstack-4.4.0/src/getstack/network_keys.py +137 -0
  101. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/notifications.py +13 -9
  102. getstack-4.4.0/src/getstack/partner_accounts.py +272 -0
  103. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/passport_header_verify.py +4 -7
  104. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/passport_session.py +1 -1
  105. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/passports.py +78 -58
  106. getstack-4.4.0/src/getstack/payments.py +163 -0
  107. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/pii_config.py +9 -28
  108. getstack-4.4.0/src/getstack/post.py +312 -0
  109. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/proxy.py +90 -22
  110. getstack-4.4.0/src/getstack/rentahuman.py +177 -0
  111. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/reviews.py +11 -10
  112. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/scan.py +13 -10
  113. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/security_events.py +4 -4
  114. getstack-4.4.0/src/getstack/service_mcp.py +145 -0
  115. getstack-4.4.0/src/getstack/services.py +235 -0
  116. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/sign_claim.py +2 -9
  117. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/skills.py +27 -19
  118. getstack-4.4.0/src/getstack/team.py +63 -0
  119. getstack-4.4.0/src/getstack/trust.py +66 -0
  120. getstack-4.4.0/src/getstack/types.py +742 -0
  121. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/usage.py +7 -5
  122. getstack-4.4.0/src/getstack/verify_agent_identity.py +157 -0
  123. getstack-4.4.0/src/getstack/verify_network.py +285 -0
  124. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/verify_offline.py +7 -3
  125. getstack-4.4.0/src/getstack/wake.py +199 -0
  126. getstack-4.4.0/src/getstack/wake_webhook.py +71 -0
  127. getstack-4.4.0/src/getstack/wallet_key.py +195 -0
  128. getstack-4.4.0/src/getstack/webhook.py +214 -0
  129. getstack-4.4.0/src/getstack/website.py +204 -0
  130. getstack-4.4.0/src/getstack/x402.py +326 -0
  131. getstack-4.4.0/tests/test_accounts.py +1159 -0
  132. getstack-4.4.0/tests/test_agent_identity.py +166 -0
  133. getstack-4.4.0/tests/test_agents_overview.py +55 -0
  134. {getstack-3.0.0 → getstack-4.4.0}/tests/test_authority.py +86 -66
  135. getstack-4.4.0/tests/test_billing.py +186 -0
  136. getstack-4.4.0/tests/test_brain.py +110 -0
  137. getstack-4.4.0/tests/test_calendar.py +175 -0
  138. getstack-4.4.0/tests/test_catalogue.py +269 -0
  139. getstack-4.4.0/tests/test_chat_channels.py +192 -0
  140. getstack-4.4.0/tests/test_connect_links.py +137 -0
  141. getstack-4.4.0/tests/test_control_policies.py +458 -0
  142. getstack-4.4.0/tests/test_control_ref.py +75 -0
  143. getstack-4.4.0/tests/test_control_socket.py +445 -0
  144. getstack-4.4.0/tests/test_credentials_files.py +132 -0
  145. {getstack-3.0.0 → getstack-4.4.0}/tests/test_delivery_methods.py +2 -2
  146. getstack-4.4.0/tests/test_drive.py +608 -0
  147. {getstack-3.0.0 → getstack-4.4.0}/tests/test_dropoffs.py +36 -9
  148. getstack-4.4.0/tests/test_errors.py +196 -0
  149. getstack-4.4.0/tests/test_flagged_content.py +76 -0
  150. {getstack-3.0.0 → getstack-4.4.0}/tests/test_fleets.py +66 -18
  151. {getstack-3.0.0 → getstack-4.4.0}/tests/test_identity_requirements.py +24 -6
  152. getstack-4.4.0/tests/test_identity_sso_domains.py +98 -0
  153. {getstack-3.0.0 → getstack-4.4.0}/tests/test_inbound_webhooks.py +7 -5
  154. getstack-4.4.0/tests/test_llm_cost_cap.py +127 -0
  155. getstack-4.4.0/tests/test_llm_images.py +73 -0
  156. getstack-4.4.0/tests/test_llm_openrouter.py +172 -0
  157. getstack-4.4.0/tests/test_making.py +160 -0
  158. getstack-4.4.0/tests/test_meetings.py +205 -0
  159. getstack-4.4.0/tests/test_memory.py +314 -0
  160. getstack-4.4.0/tests/test_message_access.py +119 -0
  161. {getstack-3.0.0 → getstack-4.4.0}/tests/test_mission_binding.py +96 -57
  162. getstack-4.4.0/tests/test_missions.py +321 -0
  163. getstack-4.4.0/tests/test_network.py +618 -0
  164. getstack-4.4.0/tests/test_parity.py +779 -0
  165. getstack-4.4.0/tests/test_partner_accounts.py +155 -0
  166. getstack-4.4.0/tests/test_post.py +248 -0
  167. getstack-4.4.0/tests/test_rentahuman.py +254 -0
  168. getstack-4.4.0/tests/test_service_connections.py +235 -0
  169. {getstack-3.0.0 → getstack-4.4.0}/tests/test_sign_claim.py +1 -1
  170. getstack-4.4.0/tests/test_team.py +78 -0
  171. getstack-4.4.0/tests/test_trust.py +95 -0
  172. getstack-4.4.0/tests/test_wake.py +260 -0
  173. getstack-4.4.0/tests/test_wallet_key.py +205 -0
  174. getstack-4.4.0/tests/test_webhook.py +187 -0
  175. getstack-4.4.0/tests/test_website_payments.py +399 -0
  176. getstack-4.4.0/tests/test_x402.py +281 -0
  177. getstack-3.0.0/CLAUDE.md +0 -77
  178. getstack-3.0.0/PKG-INFO +0 -175
  179. getstack-3.0.0/README.md +0 -148
  180. getstack-3.0.0/src/getstack/_async/delivery_methods.py +0 -85
  181. getstack-3.0.0/src/getstack/_async/dropoffs.py +0 -72
  182. getstack-3.0.0/src/getstack/_async/fleets.py +0 -82
  183. getstack-3.0.0/src/getstack/_async/identity.py +0 -120
  184. getstack-3.0.0/src/getstack/_async/inbound_webhooks.py +0 -47
  185. getstack-3.0.0/src/getstack/_async/partner_connect.py +0 -43
  186. getstack-3.0.0/src/getstack/_async/partner_tenants.py +0 -150
  187. getstack-3.0.0/src/getstack/_async/pii_config.py +0 -38
  188. getstack-3.0.0/src/getstack/_async/services.py +0 -80
  189. getstack-3.0.0/src/getstack/_async/team.py +0 -35
  190. getstack-3.0.0/src/getstack/client.py +0 -214
  191. getstack-3.0.0/src/getstack/delivery_methods.py +0 -85
  192. getstack-3.0.0/src/getstack/detector_config.py +0 -52
  193. getstack-3.0.0/src/getstack/dropoffs.py +0 -75
  194. getstack-3.0.0/src/getstack/errors.py +0 -145
  195. getstack-3.0.0/src/getstack/fleets.py +0 -82
  196. getstack-3.0.0/src/getstack/identity.py +0 -147
  197. getstack-3.0.0/src/getstack/partner_connect.py +0 -70
  198. getstack-3.0.0/src/getstack/partner_tenants.py +0 -177
  199. getstack-3.0.0/src/getstack/services.py +0 -98
  200. getstack-3.0.0/src/getstack/team.py +0 -35
  201. getstack-3.0.0/src/getstack/types.py +0 -349
  202. getstack-3.0.0/tests/test_errors.py +0 -50
  203. getstack-3.0.0/tests/test_missions.py +0 -134
  204. getstack-3.0.0/tests/test_parity.py +0 -352
  205. getstack-3.0.0/tests/test_partner_signing.py +0 -69
  206. {getstack-3.0.0 → getstack-4.4.0}/scripts/verify_sign_claim_crosslang.py +0 -0
  207. {getstack-3.0.0 → getstack-4.4.0}/src/getstack/py.typed +0 -0
  208. {getstack-3.0.0 → getstack-4.4.0}/tests/test_evidence_packs.py +0 -0
@@ -52,8 +52,12 @@ mcp-publisher.exe
52
52
  *.log
53
53
  npm-debug.log*
54
54
 
55
- # Claude Code edit audit log (per-machine paper trail of hook-logged mutations)
56
- .claude/audit/
55
+ # Claude Code edit audit log (per-machine paper trail of hook-logged mutations).
56
+ # The folder itself is tracked through a placeholder so a fresh checkout or
57
+ # worktree has it: .claude/REFERENCE.md names it, and verify-reference fails on
58
+ # a path that does not exist. Its contents stay ignored.
59
+ .claude/audit/*
60
+ !.claude/audit/.gitkeep
57
61
 
58
62
  # Claude Code per-machine state (background scheduler)
59
63
  .claude/scheduled_tasks.lock
@@ -92,3 +96,21 @@ scratchpad/
92
96
 
93
97
  # Isolated test-only LangChain, CrewAI and AutoGen verification environment.
94
98
  .tmp/fleet-framework-venv/
99
+
100
+ # Local verification output (benchmark, fleet and release evidence). Never commit.
101
+ /artifacts/
102
+
103
+ # Cleanup 2026-10: local-only files
104
+ .claude/settings.local.json
105
+ .tmp/
106
+ *.paint
107
+ *.zip
108
+ STATUS.md
109
+ design-qa.md
110
+
111
+ # Compiled facts that depend on the clock and on git history (scripts/compile-facts.mjs).
112
+ # Never committed: a commit would make them stale and two branches would always conflict
113
+ # on them. The API image bakes repo-state.json in, so the deploy workflow compiles it.
114
+ /automation/facts/repo-state.json
115
+ /automation/facts/local-state.json
116
+ /.claude/facts/repo-state.json
@@ -0,0 +1,91 @@
1
+ # getstack (Python SDK)
2
+
3
+ The Python SDK, published to PyPI as `getstack` (MIT, Python 3.9+, built with hatchling from `pyproject.toml`). It is not a pnpm workspace member and has its own tooling. Runtime dependencies: `httpx`, `cryptography`, `pyjwt`, `cbor2`. It tracks the TypeScript SDK (`packages/sdk`) service for service.
4
+
5
+ ## Structure
6
+
7
+ - `sdk-python/src/getstack/__init__.py`: the sync `Stack` and async `AsyncStack` clients, `__all__`, auth selection.
8
+ - Sync services, one module per REST domain in `sdk-python/src/getstack/` (`agents`, `passports`, `missions`, `fleets`, `accounts`, `authority`, `evidence_packs`, `llm`, `proxy`, `team`, `delivery_methods`, `detector_config`, `pii_config`, `partner_accounts`, and others).
9
+ - Async mirrors of the same services in `sdk-python/src/getstack/_async/`.
10
+ - `sdk-python/src/getstack/client.py`, `auth.py`, `agent_auth.py`, `credentials.py`, `browser_bootstrap.py`: HTTP clients and credential sources.
11
+ - `sdk-python/src/getstack/webhook.py`: `verify_webhook` (the one receiver of every webhook STACK signs, `spec/webhooks/SPEC.md`), `ReplayGuard`, `WebhookSignatureError` and `webhook_secret_key`; it must stay byte-compatible with `packages/sdk/src/webhook.ts` and `packages/shared/src/utils/standard-webhooks.ts` (`sdk-python/tests/test_webhook.py` pins vectors produced by the TypeScript reference). `control_server.verify_control_request` and `wake_webhook.verify_wake_webhook` are wrappers over it that keep their names, their whsec_-only secrets and their error classes (subclasses of `WebhookSignatureError`).
12
+ - `sdk-python/src/getstack/verify_offline.py`, `passport_header_verify.py`, `sign_claim.py`: offline Passport verification and customer-managed claim signing.
13
+ - `sdk-python/src/getstack/wallet_key.py`: the agent's wallet signer key (P-256), byte-compatible with `packages/sdk/src/wallet-key.ts`.
14
+ - `sdk-python/src/getstack/errors.py`: `StackError` with `NotFoundError`, `UnauthorizedError`, `ForbiddenError`, `ValidationError`, `PassportBlockedError`, `MissionEndedError`, and the code-mapped `GovernanceApprovalRequiredError` (a `ForbiddenError`), `AgentBudgetExceededError`, `AccountPieceNotReadyError`, `ProviderCapacityUnavailableError`, `AccountCallFailedError` (`retryable` when the status is 502), `DestinationNotAvailableError` (`reason`), `ToolPriceRefusedError` (`reason`, `provider`, `endpoint`), `ToolsUnavailableError`, `ToolRunRejectedError`, `ModelCostCapError` (`reason`; the `max_cost_cents` keyword of the `llm` calls is sent as `X-Max-Cost-Cents` and validated as a whole number of cents, 1 or more, client-side), `CatalogueUnavailableError` (`reason`), `BudgetNeedsControlsError` (a `ForbiddenError`), `PlatformSubscriptionRequiredError`, `RecipientOptedOutError` (a `ForbiddenError`), `SharedMailDailyLimitError`, `UnboundedSendRuleError`, `ControlDeniedError` (a `ForbiddenError`; `decision_id`, `reason_code`, `rule`, `retry`) and `ControlLimitExceededError` (a `ForbiddenError`; `limit['scope']` names a spend rule's counter) and `TelegramSendRefusedError` (`reason`), `PostRefusedError`, `PostUnavailableError` and `PostalAddressNotActiveError`. `raise_for_status` picks a class by `error.code` first, then by HTTP status.
15
+
16
+ ## Sync and async parity
17
+
18
+ Every service and method on `Stack` must also exist on `AsyncStack` (the async modules live under `sdk-python/src/getstack/_async/`). `sdk-python/tests/test_parity.py` is the guard: it asserts both clients expose the services in `EXPECTED_SERVICES` and the integration-critical methods in `EXPECTED_METHODS`, and that signatures such as `agents.register` match. When adding a service or method, add it to both clients and to those lists. Mirror new REST routes in `packages/sdk` too.
19
+
20
+ ## Auth and offline crypto
21
+
22
+ - Credential resolution (`Stack.__init__`): a pre-built `_auth`, then `agent_id` (agent keypair mode, `AgentKeypairAuth`), then `api_key` or `STACK_API_KEY`, then `~/.stack/credentials.json` (OAuth refresh token written by the CLI), then an interactive browser bootstrap when the process has a TTY and is not CI. Otherwise a `ValueError` is raised.
23
+ - The files under `~/.stack` follow `spec/credentials-files`: `credentials_lock` (`auth.py`) is the refresh lock the CLI and the TypeScript SDK take, `CredentialsFileAuth` reads the file again once it holds it and rejects a file with no client id or refresh token, the sign-in is created `0600`, and an agent key's `enrolled_at` is whole unix seconds (`agent_auth._unix_seconds`). `sdk-python/tests/test_credentials_files.py` pins them.
24
+ - `verify_passport_offline` (`verify_offline.py`) mirrors the JS function: EdDSA via PyJWT, with `jwks_url` or `public_jwk`. It cannot see revocation.
25
+ - `sign_claim_envelope` (`sign_claim.py`) produces COSE_Sign1 for `customer_managed` agents and must stay byte-compatible with the TS SDK and the server verifier. `sdk-python/scripts/verify_sign_claim_crosslang.py` proves it by signing in Python and verifying with the JS code; run it from the repo root (needs the JS SDK's `node_modules` for `cbor-x`).
26
+
27
+ ## Agent accounts
28
+
29
+ `stack.accounts` (`sdk-python/src/getstack/accounts.py`, `sdk-python/src/getstack/_async/accounts.py`) mirrors `/v1/accounts/*`: `open`, `get`, `list`, `close`, `set_budget` (`PUT /budget`; `None` removes it; raising or removing is a governed write), `send_email` (its answer lists `to`, `cc`, `bcc`, `attachments` and, when an address was left out, `dropped`), `reply_email` (in the thread, quoting the message), `forward_email` (a new email in no thread), `send_sms`, `send_telegram`, `resume_piece`, and the groups `telegram` (`connect`, `get`, `chats`, `disconnect`: the agent's own Telegram bot; the token goes only to `connect`), `messages`, `opt_outs` (`list`, `add(number)`, `remove(opt_out_id)`: the customer's do-not-contact list; `list` and `add` are for the owner, an admin or the account's agent, `remove` for the owner or an admin; an incoming STOP lists the number and START takes it off), `blocked_callers` (`list`, `add(number)`, `remove(blocked_caller_id)`: the customer's blocked-callers list, on the same terms as `opt_outs`; an incoming call from a listed number is turned away before it rings), `toll_free_verification`, `calls` (`place` and `answer` (a call the agent holds: `greeting`, `wait_seconds`, answered `{"call", "events"}`; with `on_behalf_of` and `brief`, a call STACK's model holds; both take `max_seconds` and `voice`), `say`, `press_keys`, `set_call_voice`, `hang_up`, `live` (the call's WebSocket, `AccountCallStream`: `text`, `press_keys`, `set_voice`, `hang_up`, the events by iteration, `close`; it needs the optional `websockets` package, the `live` extra), `get_account_voice`, `set_account_voice`, `list`, `get`, and for a call that rings on the account's number `answer(account_id, call_id, call)` and `decline(account_id, call_id)`: a call rings the agent for 30 seconds, then goes to voicemail; a wake of the source `incoming_call` carries `call_id` and `answer_by`; the call carries `caller_attestation` (A, B, C or None); a call no longer ringing is a 409 `CALL_NOT_RINGING` `StackError`, which is not counted as an action; answering is one metered action asked of the decider as `call.answer`, declining is not; both take `passport_token`, and `decline` sends `json={}`), `tools`, `workspace` (`exec`, `read_file`, `write_file`, `save_file`, `list` (without an account id, every workspace the caller may use), `set_sharing` (owner or admin: whether the customer's other agents may use one workspace), `stop`: a persistent machine with a shell and git; the acting calls take the Passport and the id of the account that owns the workspace, so another agent of the customer works in a shared one under its own Passport, what comes back is `untrusted`; `get_settings` and `set_settings(settings, account_id=None)` are the owner's idle pause, days a stopped workspace is kept and number of workspaces: `0` is off or never, `None` clears a key, an empty or unknown key is refused before any request), `browser`, `purchases`, `wallet` (`pay`; `pay_url(account_id, url, key=, max_cents=, method=, headers=, content=, passport_token=, http=)`, a purchase from an x402 seller in one call, `sdk-python/src/getstack/x402.py`, the TypeScript `payUrl` step for step: versions 1 and 2, USDC on Base with the `exact` scheme only, https only, the paid request following no redirect, `X402PaymentError` before STACK is asked otherwise), `mail_domains` (`list`, `connect`, `verify`). `open` requires `idempotency_key` (8 to 128 characters, sent as `Idempotency-Key`) and refuses a bad one before any request. Calls the account's agent makes under its Mission take `passport_token` (sent as `X-Passport-Token`); `tools.discover`, `tools.inspect` and `tools.run` require it and refuse an empty one before any request. `resume_piece` and `toll_free_verification.submit` take `governance_approval_id` (sent as `X-Governance-Approval`) for the retry after a `GovernanceApprovalRequiredError`; `open` still accepts it but opening asks for no approval, and `monthly_budget_cents` in its request is optional (it needs controls). `POST /v1/accounts/wallet-owner` is dashboard-session only and has no SDK method. `stack.services.create_connect_link`, `get_connect_link` and `list_connect_links` (one-time connect links; the list is the ones still waiting) and `stack.governance.get_approval` and `list_approvals` (`sdk-python/src/getstack/governance.py`, `sdk-python/src/getstack/_async/governance.py`; read approvals, never decide) mirror the TypeScript SDK. `stack.flagged_content` (`sdk-python/src/getstack/flagged_content.py`, `sdk-python/src/getstack/_async/flagged_content.py`) is what the customer's controls do with flagged content: `get` and `set(warning=, critical=)` (`withhold` or `deliver`; an empty or unknown change is refused before any request). `stack.billing` (`sdk-python/src/getstack/billing.py`, `sdk-python/src/getstack/_async/billing.py`) is the platform and controls subscriptions: `subscriptions`, `subscribe_platform` and `subscribe_controls`, the last two taking `governance_approval_id`. Body-less POSTs send `json={}`, because the API refuses a JSON request with an empty body.
30
+
31
+ `send_email`, `reply_email(account_id, message_id, reply)` and `forward_email(account_id, message_id, forward)` take a dict and answer an `EmailSendResult` (`message_id`, `thread_id`, `to`, `cc`, `bcc`, `attachments`). `to` is one address or a list, with `cc` and `bcc` lists (`to` is required: `cc` or `bcc` alone is refused); an empty inline file is sent like any other; OpenMail takes one To address, so the first `to` is the To and further ones are delivered as Cc. An attachment is a drive file (`{"file_id", "filename"?}`) or an inline file (`{"filename", "content_type", "content"}` with raw `bytes`, `bytearray` or `memoryview`, which `email_body` in `sdk-python/src/getstack/accounts.py` base64 encodes into `content_base64`; `content_base64` itself passes as it is). `email_body` copies the dict, leaves the caller's alone, and refuses a bad attachment (not a dict, `content` that is not bytes, `file_id` or `content_base64` together with `content`) before any request; it sets no size limit (the API's are 10 MB inline, 25 MB in all). Received messages carry `content.attachments[].file_id` or `not_saved`, `content.bcc` on a sent email and `content.thread_id`. The typed shapes are in `types.py`: `SendEmailInput`, `ReplyEmailInput`, `ForwardEmailInput`, `EmailAttachment`, `EmailSendResult`, `MessageAttachment` and `MessageEnvelope`.`tools.run` and `tools.get_run` answer a `ToolRunResult`, the run plus `untrusted` and `files` (`ToolRunFile`); the ready-tools routes (`/tools/ready/*`) are gone.
32
+
33
+ `stack.catalogue` (`sdk-python/src/getstack/catalogue.py`, `sdk-python/src/getstack/_async/catalogue.py`) mirrors `/v1/catalogue`, `/v1/catalogue/search` and `/v1/accounts/:id/catalogue`: `get(if_none_match=None)` returns a `CatalogueRead` (`not_modified`, `etag`, `document`; a `304` has no document), `search(q, kind, limit, offset)` and `for_account(account_id)`. `get` goes through `HttpClient.request_with_headers` (status, headers, body), the one client call that exposes the response headers and a `304`. `search` refuses a bad `kind` (model, tool, service, skill, account or `mcp_tool`, a tool of STACK's own MCP server, whose entry carries a `tool` object), `limit` (1 to 100) or `offset` before any request; `for_account` also answers `tools` (whether the account's agent lists each of those tools now). The typed shapes are in `types.py`. `sdk-python/tests/test_catalogue.py` pins the requests and checks the paths against the routes in `apps/api/src/hosted/routes/catalogue.ts` when the monorepo is present.
34
+
35
+ `stack.chat_channels` (`sdk-python/src/getstack/chat_channels.py`, `sdk-python/src/getstack/_async/chat_channels.py`) mirrors `/v1/chat-channels/*`: `get`, `create_identity`, `verify_identity`, `confirm_identity`, `remove_identity`, `slack_install_url`, `install_slack`, `remove_slack`. The identities are what an owner approves small held payments from, only within the limits in the policy's `review.chat`; `verify_identity`, `confirm_identity` and `install_slack` need a signed-in dashboard session (an API key gets 403).
36
+
37
+ `stack.drive` (`sdk-python/src/getstack/drive.py`, `sdk-python/src/getstack/_async/drive.py`) mirrors `/v1/drive/*`, an account's files: `upload` (exactly one of `content_text`, `content` (bytes, bytearray, memoryview or a binary file object) and `path`; `visibility`, `expires_in_seconds`), `upload_file(path, name=None, content_type=None)` (name and type default from the file; the type from a fixed extension table), `create_upload_link(name, content_type=None, size_bytes=None, visibility=None, expires_in_seconds=None)` (the one-time upload URL), `upload_to_link(link_or_url, content=|path=)` (sends the bytes there with no credential), `list`, `get`, `read` (inline, 256 KB or less), `update` (`visibility`, `expires_in_seconds`, `remove_expiry`), `copy` (`name`, `visibility`, `expires_in_seconds`: a new file of the caller's own, which does not end unless told to), `delete`, `share` (`ttl_seconds`, `max_downloads`, at most 100 and 100 when omitted; the signed URL is in the answer once; `DRIVE_LINKS_PAUSED` (409) while links are paused), `links` and `revoke_link`. Calls an agent makes take `passport_token`; the owner calls without one. Every file is untrusted content. `upload` and `update` refuse a bad request before any request. `list`'s `usage` is `{files, bytes, max_files, free_bytes, max_file_bytes, overage_bytes, download_bytes_month, download_free_bytes, links_paused, storage_unpaid}` (`links_paused` is `{since, reason}` or `None`; `storage_unpaid` is `{since, delete_on, over_bytes}` or `None`: set while the wallet could not pay for storage past the free 25 GiB, when uploads, edits and new share links are refused with `DRIVE_READ_ONLY` (409) and reading, downloading, listing and deleting still work; a top-up that covers what is due, or deleting down to within 25 GiB, lifts it at once; on `delete_on` the newest files past the first 25 GiB are deleted; there is no `max_bytes`).
38
+
39
+ `upload` is one request. `content_text` goes in a JSON body (`POST /v1/drive/files`); `content` (bytes, bytearray, memoryview or a binary file object) and `path` are the raw body of `PUT /v1/drive/files?name=&content_type=&visibility=&expires_in_seconds=` (`Content-Type: application/octet-stream`, the same auth and `X-Passport-Token` as every call). The file is read in 1 MiB chunks as it is sent (`UploadSource` in `drive.py`; the async service reads off the event loop), with `Content-Length` when the size is known (a path, bytes, a seekable file object) and chunked otherwise, so a 1 GiB file is never held in memory. The SDK sends no hash, no size and makes no complete call: the API computes the SHA-256. A file typed as text, Markdown, CSV or JSON is 10 MiB or less in every path (the drive takes a file of any type: `content_type` is only a label and is optional, `application/octet-stream` when left out; `content_type_for` falls back to it); both limits are checked before the request (`MAX_TEXT_BYTES`, `MAX_FILE_BYTES`). The upload has a 6 hour read timeout (`UPLOAD_TIMEOUT`, the API's own limit) and is never retried, since a stream cannot be replayed; the API's refusals come back as `StackError` with its code (`DRIVE_FILE_TOO_LARGE`, `DRIVE_QUOTA_EXCEEDED`, `DRIVE_FILE_EMPTY`, `DRIVE_TOO_MANY_UPLOADS` (429), `DRIVE_READ_ONLY` (409), `INSUFFICIENT_BALANCE`). `create_upload_link` is `POST /v1/drive/uploads` (the metered action) and answers `{id, url, method, name, content_type, max_bytes, expires_at}`; the URL works once for 30 minutes and is a bearer URL. `upload_to_link` is a `PUT` of the bytes to it through `HttpClient.put_to_url`, which sends no Authorization header; a transport failure there raises `StackError` `DRIVE_UPLOAD_FAILED` and a bad URL a `ValueError`, neither holding the URL, and a used, expired or foreign link is `DRIVE_UPLOAD_LINK_INVALID` (404). `HttpClient.put_stream` and `AsyncHttpClient.put_stream` are the raw-body PUT (`client.py`). `sdk-python/tests/test_drive.py` runs the real clients on an httpx `MockTransport` fake of the API for both services. `stack.dropoffs.deposit` takes `drive_files`, and `collect` returns `drive_files`.
40
+
41
+ `stack.memory` (`sdk-python/src/getstack/memory.py`, `sdk-python/src/getstack/_async/memory.py`) mirrors `/v1/memory/*`, an account's memory (Graphiti, a graph of facts with the time each held, one graph per account), with the tools of Graphiti's own MCP server and its arguments, minus any group id: `add_memory` (answers `status: "queued"` at once; `get_episodes` shows `stored`, `queued`, `processing` or `failed` with a reason), `add_triplet`, `search_nodes`, `search_memory_facts`, `get_episodes`, `get_entity_edge`, `get_episode_entities`, `delete_episode`, `delete_entity_edge` and `summarize_saga`, and the owner's `get_settings` and `update_settings(enabled=, call_memory_access=)` (what is left out keeps its value; passing neither raises `ValueError` before any request). The account's own entity types (`list_entity_types`, `create_entity_type(name, description, fields=)`, `update_entity_type`, `retire_entity_type`: a setting, free, extracted beside the ten by later writes; `search_nodes(query, entity_types=, field_filters=[{"field": ..., "value": ...}])` keeps the entities whose field of those types equals the value, and refuses `field_filters` without `entity_types` before any request), the history of writes (`get_history(max_writes=)`) and `undo_write(write_id, dry_run=)` (with every later write that depends on it; free, one delete toward the hourly rate) are the agent's and the owner's alike. Calls an agent makes take `passport_token`; the owner calls without one, through the same routes; the settings are refused to an agent by the API. The body builders (`add_memory_body` and the rest) are shared with the async mirror and refuse an empty name, text, query, fact or saga name, an unknown `source` and an empty episode list before any request. `sdk-python/tests/test_memory.py` checks the request shapes for both clients and the paths against `apps/api/src/hosted/routes/memory.ts` when the monorepo is present.
42
+
43
+ `stack.agent_identity` (`sdk-python/src/getstack/agent_identity.py`, `sdk-python/src/getstack/_async/agent_identity.py`) mirrors the public `GET /v1/agent-identity`: `lookup(key_id=, site=, agent_id=)` (exactly one; the statement is not checked), `verified(...)` (checks it against STACK's keys and returns the signed `facts`) and `urls(agent_id)`; `verify_agent_identity` (`sdk-python/src/getstack/verify_agent_identity.py`) is the offline check and `AgentIdentityVerificationError` its refusal. `stack.accounts.identity` (`get`, `update(enabled=, show_name=)`) is the owner's two switches. `sdk-python/tests/test_agent_identity.py` runs the vectors of the open kit through the check.
44
+
45
+ `stack.website` and `stack.payments` (`sdk-python/src/getstack/website.py`, `sdk-python/src/getstack/payments.py`, `sdk-python/src/getstack/_async/website.py` and `sdk-python/src/getstack/_async/payments.py`) mirror `/v1/accounts/:id/website/*`, `/v1/websites/suspend-all`, `/v1/public/site-reports` and `/v1/accounts/:id/payments/*`. The agent's calls (`publish`, `add_hostname`, `remove_hostname`, `set_prices`, `create_link`, `create_checkout_session`, `deactivate_link`) require `passport_token` and refuse an empty one before any request; reads and `check_hostname` take it optionally; `suspend`, `resume`, `suspend_all` and `disconnect_stripe` are the owner's. `site_files` builds a bundle (text as `content`, other bytes as `content_base64`). `report` is public and goes through `post_public` on both HTTP clients, which sends no Authorization header. The restricted Stripe key is never an SDK argument. Errors: `WebsitePublishRejectedError` (`findings`), `WebsiteLimitExceededError`, `WebsiteSuspendedError`, `WebsiteHostnameUnavailableError`, `PaymentConnectionRequiredError`, `StripeRequestFailedError`. `sdk-python/tests/test_website_payments.py` pins every path, header and body.
46
+
47
+ `stack.post` (`sdk-python/src/getstack/post.py`, `sdk-python/src/getstack/_async/post.py`) mirrors the post routes: the owner's street address (`get_address`, `start_address`, `connect_address`, `refresh_address`, `pause_address`, `resume_address`, `close_address`, `list_items`, `assign_item`) and an account's post and letters (`account_address`, `list_account_items`, `get_account_item`, `scan_item`, `forward_item`, `shred_item`, `check_address`, `send`, `list_letters`, `get_letter`). Agent-side calls take `passport_token`; the item requests take `idempotency_key`; `send` refuses a letter without `use_type` (operational or marketing) before any request. `connect_address` takes the supplier's agent key, a secret that is never returned. Errors: `PostRefusedError` (`reason`), `PostUnavailableError` (`reason`) and `PostalAddressNotActiveError` (`address_status`). `sdk-python/tests/test_post.py` pins the paths and the sync/async parity.
48
+
49
+ `stack.control_socket` (`sdk-python/src/getstack/control_socket.py`, `sdk-python/src/getstack/_async/control_socket.py`) mirrors `/v1/control-socket/*` and `/v1/control-decisions/*`: `get`, `set_decision_address`, `set_events_address`, `clear`, `verify`, `test`, `rotate_secret`, `set_mode`, `set_checked_types`, `list_decisions` and `get_decision`. Everything that changes the socket takes `governance_approval_id`; `verify`, `test` and `rotate_secret` send `json={}`. `sdk-python/src/getstack/control_server.py` is for the customer's own decision server: `verify_control_request` and `sign_control_answer` implement Standard Webhooks and must stay byte-compatible with `packages/shared/src/utils/standard-webhooks.ts`; `sdk-python/tests/test_control_socket.py` pins signatures produced by the TypeScript reference.
50
+
51
+ `stack.network` (`sdk-python/src/getstack/network.py`, `sdk-python/src/getstack/_async/network.py`) mirrors the STACK network: `installs` (`register`, `list`, `get`, `request_key_challenge`, `add_key`, `register_key`, `revoke_key`, `revoke`), `subscriptions` (`create` (returns the subscription's signing secret once), `list`, `delete`, `rotate_secret`, `resume`), `licences` (`revoke`, `list`: revoke a licence key STACK issued to the account before it expires, by presenting it), and `publish_revocation`, `jwks`, `signed_revocations`, `revocations`, `verify` and `verified`. Registering a key is a governance action (`request_key_challenge` and `register_key` take `governance_approval_id`); `jwks`, `signed_revocations`, `revocations`, `verify` and `verified` are public and send no credential (`HttpClient.public_request`). `network_keys.py` holds `InstallKey` (generate, PEM, thumbprint, the proof of possession and the single-use signed request), `network_install.py` the `InstallClient` and `AsyncInstallClient` an install calls with (they send a fresh proof as the bearer value and no account credential), and `verify_network.py` the offline checks `verify_countersigned_passport`, `verify_revocation_list`, `revocation_covers` (matches a verified list's entries to a countersigned passport on the subject AND the install: an entry of another install, or with none, is ignored), `verify_verified_statement` and `verify_detection_rules`. `publish_revocation` takes the `install` the subject belongs to for every kind. `sdk-python/tests/test_network.py` reads the server's deterministic vectors from `spec/network/test-vectors.json` and fails when the file is missing.
52
+
53
+ `stack.control_policies` and `stack.control_reviews` (`sdk-python/src/getstack/control_policies.py`, `sdk-python/src/getstack/_async/control_policies.py`) mirror `/v1/control-policies/*` and `/v1/control-reviews/*`: `list`, `get`, `set`, `delete`, `start_from_current_access`, `simulate` and `revisions` for policies, and `list` and `get` for reviews (read only: a held action is decided through the ordinary governance approval). `get`, `set` and `delete` take a scope, `"default"` or an agent id; `set` and `delete` take `expected_revision` (`set` omits it to create, `delete` sends it as a query parameter) and, with `start_from_current_access`, `governance_approval_id`, because loosening and deleting a policy need a person in a browser. A rule's `"recipients": "per_mission"` (`POLICY_RECIPIENTS_PER_MISSION` in `control_policies.py`) leaves who a send may go to to each Mission, whose `missions.open` takes `recipients`, `recipient_pins` and `reply_to_message` (the operator form of `start` takes them inside `mission`; `MISSION_RECIPIENT_ANY_PATH` in `missions.py` is the `*` pin path), and `simulate`'s `call` takes `mission_id`; a refusal's `reason_code` is `recipients_not_pinned` or `recipient_not_allowed`. The account's own `recipients.email`, `sms` and `call` take a list or `"per_mission"` too: under it `accounts.send_email`, `send_sms` and `calls.place` take `reply_to_message` (the stored message id, `amsg_*`; a plain dict key, typed on `SendEmailInput`), the send goes only to who wrote that message, and an id that is not one of the account's received messages is a `NotFoundError`; `reply_email` takes no new key (the message in the path is the pin) and `forward_email` has no pin. `simulate` refuses a call with no `action`, or neither `agent_id` nor `definition`, before any request. `stack.reviews` is the unrelated flagged-checkout reviews. `sdk-python/tests/test_control_policies.py` pins the paths and checks them against the routes in `apps/api/src/routes/control-policies.ts` when the monorepo is present.
54
+
55
+ `stack.wakes` (`sdk-python/src/getstack/wake.py`, `sdk-python/src/getstack/_async/wake.py`) mirrors `/v1/agents/:agentId/wakes`, `/v1/agents/:agentId/wake/*` and `/v1/wake/*`, and `stack.calendar` (`sdk-python/src/getstack/calendar.py`, `sdk-python/src/getstack/_async/calendar.py`: `list_events`, `get_event`, `agenda`, `create_event`, `update_event`, `cancel_event`, `respond`, `decline_proposal`, `feed`, `rotate_feed`, `revoke_feed`; one action each to make, change, cancel and answer; the feed URL is returned once) `/v1/accounts/:id/calendar/*` (wake-ups are every agent's, with or without an account; a `decision` wake names a pending item and how it ended in `event`): `wakes.list` (`status="open"` is the agent's queue), `get`, `acknowledge`, `get_settings`, `set_settings` (incl. `ring_incoming_calls`: `False` sends every incoming call straight to voicemail), `rotate_webhook_secret`, `test_webhook`, `list_rules`, `create_rule`, `update_rule`, `delete_rule` and the schedule methods. An agent id addresses one agent, none the customer's defaults ; the agent's own calls take `passport_token`; a webhook secret comes back once, to an API key or a session. `sdk-python/src/getstack/wake_webhook.py` is for the agent's own endpoint: `verify_wake_webhook` is Standard Webhooks over `control_server.verify_control_request` and raises `WakeSignatureError`. `sdk-python/tests/test_wake.py` pins the paths and checks them against `apps/api/src/hosted/routes/wake.ts`, and `test_calendar.py` against `account-calendar.ts` when the monorepo is present.
56
+
57
+ `stack.meetings` (`sdk-python/src/getstack/meetings.py`, `sdk-python/src/getstack/_async/meetings.py`: `join(account_id, {"event_id": ...})`, `say(account_id, meeting_id, text=, wait_seconds=)`, `chat`, `leave`, `list`, `get` and `live`, a meeting's WebSocket as `MeetingStream` (`text`, `chat`, `leave`, the events by iteration, `close`; it needs the optional `websockets` package, the `live` extra)) mirrors `/v1/accounts/:id/meetings/*`: the agent in the Daily room of one of its own calendar events, STACK running no model; joining is one metered action, the rest are free; the agent's calls take `passport_token`; a participant's words and name are a stranger's text. `sdk-python/tests/test_meetings.py` pins the paths and checks them against `apps/api/src/hosted/routes/account-meetings.ts` when the monorepo is present.
58
+ `stack.rentahuman` (`sdk-python/src/getstack/rentahuman.py`, `sdk-python/src/getstack/_async/rentahuman.py`: `join`, `complete_join`, `join_with_key`, `fund`, `complete_fund`, `fund_with_key` and `get`, the TypeScript SDK's `rentahuman` with `accept_terms=True` required before any request; `sign_rentahuman_payment(key, start)` makes the agent's signature from the payment `join` or `fund` returned) and `stack.proxy.service_tools(service)` and `service_call_tool(service, tool, arguments)` (`sdk-python/src/getstack/service_mcp.py`: a connected service that speaks MCP over HTTP through the credential proxy, `untrusted` answers, an operation id made when none is given; a person who writes to the agent through RentAHuman wakes it with the source `service_event`). `sdk-python/tests/test_rentahuman.py` pins the requests for both clients and, when the monorepo is present, that the endpoint table equals `packages/shared/src/constants/service-mcp.ts`.
59
+
60
+ `sdk-python/src/getstack/wallet_key.py` must stay byte-compatible with the TS helper: RFC 8785 canonical JSON (keys in UTF-16 code unit order, safe integers only), `encodeURIComponent` of the wallet id, DER ECDSA-SHA256, `wallet-auth:` PKCS#8. `sdk-python/tests/test_wallet_key.py` pins the payload. Every entry point raises `WalletKeyInSandboxError` when `STACK_SANDBOX` is set to anything but empty or `0`. `AgentWalletKey` never shows the private key through `repr`/`str` and refuses pickling and copying.
61
+
62
+ `stack.agents` (`sdk-python/src/getstack/agents.py`, `sdk-python/src/getstack/_async/agents.py`) mirrors `/v1/agents/*`: `register` (a new agent starts `logged`; `eval_traffic` is sent only when set), `get`, `list`, `overview(limit=, cursor=)` (one page of every agent of the account with its status, trust, pieces, held items, queued wake-ups, handoffs and spend this month, as a dict: `GET /v1/agents/overview`, for the owner, an admin or a read-only member, never an agent; `sdk-python/tests/test_agents_overview.py`), `update`, `suspend`, `activate`, `delete`, `unblock`, and `setup(agent, grants, allowed_hosts, governance_approval_id=None)`, which registers an agent with its first grants and the hosts its connections' credentials may go to as one human approval (retry with `governance_approval_id` once a person approved it in the browser), and `dismiss_warnings(agent_id)`, which resolves an agent's open warnings and hides new ones of the same kinds for a day (criticals stay open).
63
+
64
+ ## Mission context manager
65
+
66
+ `stack.passports.mission(agent_id=..., intent=..., services=[...])` (and `async with` on `AsyncStack`) opens a Mission and its Passport in one call, submits checkpoints on a timer, checks out on exit, then completes the Mission. If the block raises, the Mission is revoked instead. Pass `mission_id="ms_..."` to bind an existing Mission, which is then left open on exit. `continuous_mission` rotates Passports under one Mission and raises `MissionEndedError` when the Mission ends. The TypeScript SDK has no equivalent context manager; keep keyword names aligned if one is added.
67
+
68
+ ## Run and test
69
+
70
+ ```bash
71
+ cd sdk-python
72
+ python -m pip install -e ".[dev]" # pytest, ruff, mypy
73
+ ruff check . # lint, import order (rules in pyproject.toml)
74
+ ruff format --check . # formatting, line length 120
75
+ mypy src # strict typing of src/ only; tests are not type-checked
76
+ python -m pytest -q # same tests as `pnpm verify:python`
77
+ ```
78
+
79
+ Run the three checks with a Python 3.10+ interpreter (current mypy no longer runs on 3.9). Fix findings in the code; the only suppressions are narrow `# type: ignore[code]` comments in tests. The HTTP client returns untyped JSON (`Any`), so service methods wrap it in `cast("<return type>", ...)` to satisfy `warn_return_any`. A service class that defines a `list` method must annotate later signatures as `builtins.list[...]`.
80
+
81
+ The integration-guide smoke test (`scripts/smoke-test-integration-guides.py`, with `scripts/smoke-test-integration-guides-setup.mjs`) needs a local API (port 3001); `scripts/release.mjs` runs it during `/publish sdk-python` when the API is reachable and aborts the release on failure.
82
+
83
+ ## Publishing
84
+
85
+ A change to this package must be released in the same session: bump `version` in `pyproject.toml` and run `/publish sdk-python <bump>`. That runs `scripts/release.mjs`, tags `sdk-python-v*`, and `publish-sdk-python.yml` uploads to PyPI. Do not run `twine` by hand. Versions are independent of the TypeScript SDK.
86
+
87
+ ## Gotchas
88
+
89
+ - The grant field on the wire is `service_connection_id`. Notification rules use `/v1/notifications/channels` (`notifications`); delivery methods use `/v1/notifications/destinations` (`delivery_methods`).
90
+ - The monorepo's JS lockfile does not resolve Python dependencies.
91
+ - The editable install may point at the main checkout, not at the worktree you are in, so a test run there would exercise the wrong source. In a worktree run `PYTHONPATH=src python -m pytest -q`, and pass `--basetemp <a writable folder>` when pytest's default temporary folder is not writable.
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2026 STACK
3
+ Copyright (c) 2026 Tomi Lupsakko
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal