getstack 2.0.0__tar.gz → 4.0.0__tar.gz

{getstack-2.0.0 → getstack-4.0.0}/.gitignore

@@ -92,3 +92,14 @@ scratchpad/
 
 # Isolated test-only LangChain, CrewAI and AutoGen verification environment.
 .tmp/fleet-framework-venv/
+
+# Local verification output (benchmark, fleet and release evidence). Never commit.
+/artifacts/
+
+# Cleanup 2026-10: local-only files
+.claude/settings.local.json
+.tmp/
+*.paint
+*.zip
+STATUS.md
+design-qa.md

getstack-4.0.0/CLAUDE.md

@@ -0,0 +1,50 @@
+# getstack (Python SDK)
+
+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.
+
+## Structure
+
+- `sdk-python/src/getstack/__init__.py`: the sync `Stack` and async `AsyncStack` clients, `__all__`, auth selection.
+- Sync services, one module per REST domain in `sdk-python/src/getstack/` (`agents`, `passports`, `missions`, `fleets`, `authority`, `evidence_packs`, `llm`, `proxy`, `team`, `delivery_methods`, `detector_config`, `pii_config`, `partner_tenants`, `partner_connect`, and others).
+- Async mirrors of the same services in `sdk-python/src/getstack/_async/`.
+- `sdk-python/src/getstack/client.py`, `auth.py`, `agent_auth.py`, `credentials.py`, `browser_bootstrap.py`: HTTP clients and credential sources.
+- `sdk-python/src/getstack/verify_offline.py`, `passport_header_verify.py`, `sign_claim.py`: offline Passport verification and customer-managed claim signing.
+- `sdk-python/src/getstack/errors.py`: `StackError` with `NotFoundError`, `UnauthorizedError`, `ForbiddenError`, `ValidationError`, `PassportBlockedError`, `MissionEndedError`.
+
+## Sync and async parity
+
+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.
+
+## Auth and offline crypto
+
+- 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.
+- `verify_passport_offline` (`verify_offline.py`) mirrors the JS function: EdDSA via PyJWT, with `jwks_url` or `public_jwk`. It cannot see revocation.
+- `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`).
+
+## Mission context manager
+
+`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.
+
+## Run and test
+
+```bash
+cd sdk-python
+python -m pip install -e ".[dev]"   # pytest, ruff, mypy
+ruff check .                       # lint, import order (rules in pyproject.toml)
+ruff format --check .              # formatting, line length 120
+mypy src                           # strict typing of src/ only; tests are not type-checked
+python -m pytest -q                # same tests as `pnpm verify:python`
+```
+
+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[...]`.
+
+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.
+
+## Publishing
+
+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.
+
+## Gotchas
+
+- 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`).
+- The monorepo's JS lockfile does not resolve Python dependencies.

{getstack-2.0.0 → getstack-4.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: getstack
-Version: 2.0.0
+Version: 4.0.0
 Summary: Python SDK for STACK — trust infrastructure for AI agents
 Project-URL: Homepage, https://getstack.run
 Project-URL: Documentation, https://getstack.run/docs/sdk
@@ -23,6 +23,10 @@ Requires-Dist: cbor2>=5.6.0
 Requires-Dist: cryptography>=42.0.0
 Requires-Dist: httpx>=0.25.0
 Requires-Dist: pyjwt>=2.8.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # getstack
@@ -54,13 +58,24 @@ def run_fleet_mission_example(stack, request, provider_url="https://slack.com/ap
     repeated = stack.missions.start(request)
     assert repeated["mission_id"] == started["mission_id"]
     operation_id = hashlib.sha256(json.dumps([started["mission_id"], "support-update"]).encode()).hexdigest()
-    response = stack.proxy.request("slack", provider_url, "POST",
+    response = stack.proxy.request(
+        "slack",
+        provider_url,
+        "POST",
         body={"channel": "C123", "text": "Support update"},
-        passport_token=started["passport"]["token"], authority_request_id=operation_id)
+        passport_token=started["passport"]["token"],
+        authority_request_id=operation_id,
+    )
     assert response.status == 200
     try:
-        stack.proxy.request("slack", provider_url, "POST", body={"channel": "OTHER", "text": "Support update"},
-            passport_token=started["passport"]["token"], authority_request_id=operation_id + "_denied")
+        stack.proxy.request(
+            "slack",
+            provider_url,
+            "POST",
+            body={"channel": "OTHER", "text": "Support update"},
+            passport_token=started["passport"]["token"],
+            authority_request_id=operation_id + "_denied",
+        )
     except StackError as error:
         assert error.status_code == 403
     else:
@@ -125,8 +140,15 @@ stack.agents.list()
 stack.agents.update(agent_id, **fields)
 stack.agents.unblock(agent_id)
 
+# Missions (every passport is issued for exactly one Mission)
+stack.missions.open(intent_summary, agent_id=None, intent_services=None, ...)
+stack.missions.start(agent_id=agent_id, mission={"intent_summary": "..."}, passport=None)
+stack.missions.complete(mission_id)  # also revokes the Mission's passports
+stack.missions.revoke(mission_id, reason="operator_initiated_clean")
+
 # Passports
-stack.passports.issue(agent_id, intent=None, services=None, ...)
+stack.passports.issue(agent_id, mission_ids=[mission_id], intent=None, services=None, ...)
+stack.passports.mission(agent_id, intent, services, ...)  # context manager: Mission + passport, closed on exit
 stack.passports.verify(token)
 stack.passports.revoke(jti, reason=None)
 stack.passports.checkpoint(jti, services_used, actions_count, ...)
@@ -148,9 +170,9 @@ stack.reviews.list(status="flagged")
 stack.reviews.decide(checkout_id, decision, notes=None, block_future=False)
 
 # Drop-offs
-stack.dropoffs.create(from_agent_id, to_agent_id, schema, ...)
-stack.dropoffs.deposit(dropoff_id, data, agent_id)
-stack.dropoffs.collect(dropoff_id, agent_id)
+stack.dropoffs.create(from_agent_id, to_agent_id, schema, ..., passport_token=None)
+stack.dropoffs.deposit(dropoff_id, data, agent_id, passport_token=None)
+stack.dropoffs.collect(dropoff_id, agent_id, passport_token=None)
 
 # Notifications
 stack.notifications.list()
@@ -161,6 +183,18 @@ stack.notifications.delete(channel_id)
 stack.audit.list(page=1, limit=50, action=None, agent_id=None)
 ```
 
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+ruff check .
+ruff format --check .
+mypy src
+python -m pytest -q
+```
+
+The package ships `py.typed`; `mypy src` runs in strict mode.
+
 ## Links
 
 - [Documentation](https://getstack.run/docs/sdk)

{getstack-2.0.0 → getstack-4.0.0}/README.md

@@ -27,13 +27,24 @@ def run_fleet_mission_example(stack, request, provider_url="https://slack.com/ap
     repeated = stack.missions.start(request)
     assert repeated["mission_id"] == started["mission_id"]
     operation_id = hashlib.sha256(json.dumps([started["mission_id"], "support-update"]).encode()).hexdigest()
-    response = stack.proxy.request("slack", provider_url, "POST",
+    response = stack.proxy.request(
+        "slack",
+        provider_url,
+        "POST",
         body={"channel": "C123", "text": "Support update"},
-        passport_token=started["passport"]["token"], authority_request_id=operation_id)
+        passport_token=started["passport"]["token"],
+        authority_request_id=operation_id,
+    )
     assert response.status == 200
     try:
-        stack.proxy.request("slack", provider_url, "POST", body={"channel": "OTHER", "text": "Support update"},
-            passport_token=started["passport"]["token"], authority_request_id=operation_id + "_denied")
+        stack.proxy.request(
+            "slack",
+            provider_url,
+            "POST",
+            body={"channel": "OTHER", "text": "Support update"},
+            passport_token=started["passport"]["token"],
+            authority_request_id=operation_id + "_denied",
+        )
     except StackError as error:
         assert error.status_code == 403
     else:
@@ -98,8 +109,15 @@ stack.agents.list()
 stack.agents.update(agent_id, **fields)
 stack.agents.unblock(agent_id)
 
+# Missions (every passport is issued for exactly one Mission)
+stack.missions.open(intent_summary, agent_id=None, intent_services=None, ...)
+stack.missions.start(agent_id=agent_id, mission={"intent_summary": "..."}, passport=None)
+stack.missions.complete(mission_id)  # also revokes the Mission's passports
+stack.missions.revoke(mission_id, reason="operator_initiated_clean")
+
 # Passports
-stack.passports.issue(agent_id, intent=None, services=None, ...)
+stack.passports.issue(agent_id, mission_ids=[mission_id], intent=None, services=None, ...)
+stack.passports.mission(agent_id, intent, services, ...)  # context manager: Mission + passport, closed on exit
 stack.passports.verify(token)
 stack.passports.revoke(jti, reason=None)
 stack.passports.checkpoint(jti, services_used, actions_count, ...)
@@ -121,9 +139,9 @@ stack.reviews.list(status="flagged")
 stack.reviews.decide(checkout_id, decision, notes=None, block_future=False)
 
 # Drop-offs
-stack.dropoffs.create(from_agent_id, to_agent_id, schema, ...)
-stack.dropoffs.deposit(dropoff_id, data, agent_id)
-stack.dropoffs.collect(dropoff_id, agent_id)
+stack.dropoffs.create(from_agent_id, to_agent_id, schema, ..., passport_token=None)
+stack.dropoffs.deposit(dropoff_id, data, agent_id, passport_token=None)
+stack.dropoffs.collect(dropoff_id, agent_id, passport_token=None)
 
 # Notifications
 stack.notifications.list()
@@ -134,6 +152,18 @@ stack.notifications.delete(channel_id)
 stack.audit.list(page=1, limit=50, action=None, agent_id=None)
 ```
 
+## Development
+
+```bash
+python -m pip install -e ".[dev]"
+ruff check .
+ruff format --check .
+mypy src
+python -m pytest -q
+```
+
+The package ships `py.typed`; `mypy src` runs in strict mode.
+
 ## Links
 
 - [Documentation](https://getstack.run/docs/sdk)

{getstack-2.0.0 → getstack-4.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "getstack"
-version = "2.0.0"
+version = "4.0.0"
 description = "Python SDK for STACK — trust infrastructure for AI agents"
 readme = "README.md"
 license = "MIT"
@@ -46,3 +46,36 @@ Repository = "https://github.com/getstack-run/sdk-python"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/getstack"]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "ruff>=0.9.0",
+    "mypy>=1.13.0",
+]
+
+[tool.ruff]
+line-length = 120
+target-version = "py39"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort import order
+    "B",   # flake8-bugbear
+    "UP",  # pyupgrade
+    "SIM", # flake8-simplify
+    "C4",  # flake8-comprehensions
+    "RUF", # ruff-specific rules
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["getstack"]
+
+[tool.mypy]
+strict = true
+mypy_path = "src"
+files = ["src"]