getstack 1.3.0__tar.gz → 1.4.0__tar.gz

{getstack-1.3.0 → getstack-1.4.0}/.gitignore

@@ -89,3 +89,6 @@ scratchpad/
 
 # Local venv for the AgentDojo benchmark harness (never commit)
 .venv-agentdojo/
+
+# Isolated test-only LangChain, CrewAI and AutoGen verification environment.
+.tmp/fleet-framework-venv/

{getstack-1.3.0 → getstack-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: getstack
-Version: 1.3.0
+Version: 1.4.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
@@ -44,32 +44,44 @@ npx -y @getstackrun/cli auth login
 ```
 
 ```python
-from getstack import Stack
-
-# Zero-arg constructor reads ~/.stack/credentials.json (OAuth refresh token).
-# Falls back to STACK_API_KEY env var, then constructor api_key= for CI.
-stack = Stack()
-
-# 1. Register an agent (one-time)
-agent = stack.agents.register("my-agent", accountability_mode="enforced")
-
-# 2. In your agent runtime, switch to per-agent keypair mode
-agent_stack = Stack(agent_id=agent.id)
-# First run: generates an Ed25519 keypair locally + enrolls the public
-# half via /v1/agents/<id>/enroll. Persisted at ~/.stack/agents/<id>.json
-# (mode 0600). Every subsequent call signs a fresh 60-second JWT.
-
-# 3. Run a mission with automatic checkpoints and checkout
-with agent_stack.passports.mission(
-    agent_id=agent.id,
-    intent="Process invoices from Slack",
-    services=["slack", "stripe"],
-    checkpoint_interval="5m",
-) as mission:
-    mission.log("slack", "read_channel", "#invoices")
-    mission.log("stripe", "create_invoice")
-    # Checkpoints are submitted automatically on schedule
-# Checkout is submitted automatically when the block exits
+import hashlib
+import json
+from getstack.errors import StackError
+
+
+def run_fleet_mission_example(stack, request, provider_url="https://slack.com/api/chat.postMessage"):
+    started = stack.missions.start(request)
+    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",
+        body={"channel": "C123", "text": "Support update"},
+        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")
+    except StackError as error:
+        assert error.status_code == 403
+    else:
+        raise AssertionError("Expected channel restriction")
+    before = stack.missions.get(started["mission_id"])
+    renewed = stack.missions.renew(started["mission_id"])
+    after = stack.missions.get(renewed["mission_id"])
+    assert renewed["mission_id"] == started["mission_id"]
+    assert after["fleet"]["limits"] == before["fleet"]["limits"]
+    assert after["fleet"]["usage"] == before["fleet"]["usage"]
+    completed = stack.missions.complete(started["mission_id"], output={"done": True})
+    assert completed["terminal_state"] == "completed_successful"
+    stopped = stack.missions.start({**request, "idempotency_key": request["idempotency_key"] + "-stop"})
+    stack.missions.revoke(stopped["mission_id"], reason="operator_initiated_clean")
+    try:
+        stack.missions.renew(stopped["mission_id"])
+    except StackError:
+        pass
+    else:
+        raise AssertionError("Expected revoked Mission")
+    return {"mission_id": started["mission_id"], "operation_id": operation_id, "completed": True, "revoked": True}
 ```
 
 ## Authentication
@@ -94,23 +106,15 @@ stack = Stack()
 
 See [/docs/security/stack-auth](https://getstack.run/docs/security/stack-auth) for the full auth model and [/docs/security/agent-keys](https://getstack.run/docs/security/agent-keys) for the per-agent keypair story.
 
-## Continuous missions (24/7 agents)
+## Renew a Mission's Passport
 
 ```python
-for mission in stack.passports.continuous_mission(
-    agent_id=agent.id,
-    intent="Monitor Slack channels",
-    services=["slack"],
-    rotation_interval="4h",
-    checkpoint_interval="5m",
-):
-    while not mission.should_rotate:
-        event = wait_for_event()
-        mission.log("slack", "read_message")
-        process(event)
-    # Passport rotates automatically at the boundary
+renewed = stack.missions.renew(mission_id)
+passport_token = renewed["passport"]["token"]
 ```
 
+Renewal keeps the same Mission, permission and recorded usage. Its deadline and limits still apply. Start a new Mission for the next job.
+
 ## Services
 
 ```python

{getstack-1.3.0 → getstack-1.4.0}/README.md

@@ -17,32 +17,44 @@ npx -y @getstackrun/cli auth login
 ```
 
 ```python
-from getstack import Stack
-
-# Zero-arg constructor reads ~/.stack/credentials.json (OAuth refresh token).
-# Falls back to STACK_API_KEY env var, then constructor api_key= for CI.
-stack = Stack()
-
-# 1. Register an agent (one-time)
-agent = stack.agents.register("my-agent", accountability_mode="enforced")
-
-# 2. In your agent runtime, switch to per-agent keypair mode
-agent_stack = Stack(agent_id=agent.id)
-# First run: generates an Ed25519 keypair locally + enrolls the public
-# half via /v1/agents/<id>/enroll. Persisted at ~/.stack/agents/<id>.json
-# (mode 0600). Every subsequent call signs a fresh 60-second JWT.
-
-# 3. Run a mission with automatic checkpoints and checkout
-with agent_stack.passports.mission(
-    agent_id=agent.id,
-    intent="Process invoices from Slack",
-    services=["slack", "stripe"],
-    checkpoint_interval="5m",
-) as mission:
-    mission.log("slack", "read_channel", "#invoices")
-    mission.log("stripe", "create_invoice")
-    # Checkpoints are submitted automatically on schedule
-# Checkout is submitted automatically when the block exits
+import hashlib
+import json
+from getstack.errors import StackError
+
+
+def run_fleet_mission_example(stack, request, provider_url="https://slack.com/api/chat.postMessage"):
+    started = stack.missions.start(request)
+    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",
+        body={"channel": "C123", "text": "Support update"},
+        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")
+    except StackError as error:
+        assert error.status_code == 403
+    else:
+        raise AssertionError("Expected channel restriction")
+    before = stack.missions.get(started["mission_id"])
+    renewed = stack.missions.renew(started["mission_id"])
+    after = stack.missions.get(renewed["mission_id"])
+    assert renewed["mission_id"] == started["mission_id"]
+    assert after["fleet"]["limits"] == before["fleet"]["limits"]
+    assert after["fleet"]["usage"] == before["fleet"]["usage"]
+    completed = stack.missions.complete(started["mission_id"], output={"done": True})
+    assert completed["terminal_state"] == "completed_successful"
+    stopped = stack.missions.start({**request, "idempotency_key": request["idempotency_key"] + "-stop"})
+    stack.missions.revoke(stopped["mission_id"], reason="operator_initiated_clean")
+    try:
+        stack.missions.renew(stopped["mission_id"])
+    except StackError:
+        pass
+    else:
+        raise AssertionError("Expected revoked Mission")
+    return {"mission_id": started["mission_id"], "operation_id": operation_id, "completed": True, "revoked": True}
 ```
 
 ## Authentication
@@ -67,23 +79,15 @@ stack = Stack()
 
 See [/docs/security/stack-auth](https://getstack.run/docs/security/stack-auth) for the full auth model and [/docs/security/agent-keys](https://getstack.run/docs/security/agent-keys) for the per-agent keypair story.
 
-## Continuous missions (24/7 agents)
+## Renew a Mission's Passport
 
 ```python
-for mission in stack.passports.continuous_mission(
-    agent_id=agent.id,
-    intent="Monitor Slack channels",
-    services=["slack"],
-    rotation_interval="4h",
-    checkpoint_interval="5m",
-):
-    while not mission.should_rotate:
-        event = wait_for_event()
-        mission.log("slack", "read_message")
-        process(event)
-    # Passport rotates automatically at the boundary
+renewed = stack.missions.renew(mission_id)
+passport_token = renewed["passport"]["token"]
 ```
 
+Renewal keeps the same Mission, permission and recorded usage. Its deadline and limits still apply. Start a new Mission for the next job.
+
 ## Services
 
 ```python

{getstack-1.3.0 → getstack-1.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "getstack"
-version = "1.3.0"
+version = "1.4.0"
 description = "Python SDK for STACK — trust infrastructure for AI agents"
 readme = "README.md"
 license = "MIT"

{getstack-1.3.0 → getstack-1.4.0}/src/getstack/__init__.py

@@ -1,39 +1,51 @@
-"""STACK Python SDK — trust infrastructure for AI agents.
-
-Usage::
-
-    from getstack import Stack
-
-    stack = Stack(api_key="sk_live_...")
-    agent = stack.agents.register("my-agent")
-
-    with stack.passports.mission(
-        agent_id=agent.id,
-        intent="Process invoices",
-        services=["slack", "stripe"],
-    ) as mission:
-        mission.log("slack", "read_channel", "#invoices")
-        mission.log("stripe", "create_invoice")
-
-For OAuth auth::
-
-    stack = Stack.from_oauth(
-        client_id="...",
-        client_secret="...",
-        access_token="...",
-        refresh_token="...",
-    )
-
-For async usage::
-
-    from getstack import AsyncStack
-
-    stack = AsyncStack(api_key="sk_live_...")
+"""STACK Python SDK.
+
+Fleet Mission example::
+
+    import hashlib
+    import json
+    from getstack.errors import StackError
+
+
+    def run_fleet_mission_example(stack, request, provider_url="https://slack.com/api/chat.postMessage"):
+        started = stack.missions.start(request)
+        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",
+            body={"channel": "C123", "text": "Support update"},
+            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")
+        except StackError as error:
+            assert error.status_code == 403
+        else:
+            raise AssertionError("Expected channel restriction")
+        before = stack.missions.get(started["mission_id"])
+        renewed = stack.missions.renew(started["mission_id"])
+        after = stack.missions.get(renewed["mission_id"])
+        assert renewed["mission_id"] == started["mission_id"]
+        assert after["fleet"]["limits"] == before["fleet"]["limits"]
+        assert after["fleet"]["usage"] == before["fleet"]["usage"]
+        completed = stack.missions.complete(started["mission_id"], output={"done": True})
+        assert completed["terminal_state"] == "completed_successful"
+        stopped = stack.missions.start({**request, "idempotency_key": request["idempotency_key"] + "-stop"})
+        stack.missions.revoke(stopped["mission_id"], reason="operator_initiated_clean")
+        try:
+            stack.missions.renew(stopped["mission_id"])
+        except StackError:
+            pass
+        else:
+            raise AssertionError("Expected revoked Mission")
+        return {"mission_id": started["mission_id"], "operation_id": operation_id, "completed": True, "revoked": True}
 """
 
 from __future__ import annotations
 
 import os
+from importlib.metadata import PackageNotFoundError, version
 from typing import Any
 
 from .auth import ApiKeyAuth, SessionAuth, OAuthAuth, CredentialsFileAuth
@@ -62,6 +74,8 @@ from .verify_offline import verify_passport_offline
 from .sign_claim import sign_claim_envelope
 from .intents import IntentsService
 from .missions import MissionsService
+from .fleets import FleetsService
+from ._async.fleets import AsyncFleetsService
 from .evidence_packs import EvidencePacksService
 from .llm import LlmService
 from .team import TeamService
@@ -107,7 +121,10 @@ from .errors import (
     PassportBlockedError,
 )
 
-__version__ = "0.2.0"
+try:
+    __version__ = version("getstack")
+except PackageNotFoundError:
+    __version__ = "0+unknown"
 
 
 def _build_static_auth(
@@ -191,6 +208,8 @@ __all__ = [
     "DetectorConfigService",
     "PiiConfigService",
     "AuthorityService",
+    "FleetsService",
+    "AsyncFleetsService",
     "AsyncAuthorityService",
     # Offline / customer-managed crypto (parity with the JS SDK)
     "verify_passport_offline",
@@ -234,11 +253,10 @@ class Stack:
         if _auth:
             auth: ApiKeyAuth | SessionAuth | OAuthAuth | CredentialsFileAuth | AgentKeypairAuth = _auth
         elif agent_id:
-            static_auth = _build_static_auth(api_key=api_key, base_url=base_url)
             auth = AgentKeypairAuth(
                 agent_id=agent_id,
                 api_base_url=base_url,
-                bearer_provider=lambda: static_auth.get_headers()["Authorization"].split(" ", 1)[1],
+                bearer_provider=lambda: _build_static_auth(api_key=api_key, base_url=base_url).get_headers()["Authorization"].split(" ", 1)[1],
             )
         elif api_key or os.environ.get("STACK_API_KEY"):
             auth = ApiKeyAuth(api_key or os.environ["STACK_API_KEY"])
@@ -262,6 +280,7 @@ class Stack:
         self.identity = IdentityService(self._client)
         self.intents = IntentsService(self._client)
         self.missions = MissionsService(self._client)
+        self.fleets = FleetsService(self._client)
         self.evidence_packs = EvidencePacksService(self._client)
         self.llm = LlmService(self._client)
         self.inbound_webhooks = InboundWebhookService(self._client)
@@ -381,11 +400,10 @@ class AsyncStack:
         if _auth:
             auth: ApiKeyAuth | SessionAuth | OAuthAuth | CredentialsFileAuth | AgentKeypairAuth = _auth
         elif agent_id:
-            static_auth = _build_static_auth(api_key=api_key, base_url=base_url)
             auth = AgentKeypairAuth(
                 agent_id=agent_id,
                 api_base_url=base_url,
-                bearer_provider=lambda: static_auth.get_headers()["Authorization"].split(" ", 1)[1],
+                bearer_provider=lambda: _build_static_auth(api_key=api_key, base_url=base_url).get_headers()["Authorization"].split(" ", 1)[1],
             )
         elif api_key or os.environ.get("STACK_API_KEY"):
             auth = ApiKeyAuth(api_key or os.environ["STACK_API_KEY"])
@@ -441,6 +459,7 @@ class AsyncStack:
         self.identity = AsyncIdentityService(self._client)
         self.intents = AsyncIntentsService(self._client)
         self.missions = AsyncMissionsService(self._client)
+        self.fleets = AsyncFleetsService(self._client)
         self.llm = AsyncLlmService(self._client)
         self.inbound_webhooks = AsyncInboundWebhookService(self._client)
         self.partner_tenants = AsyncPartnerTenantsService(self._client)

getstack-1.4.0/src/getstack/_async/fleets.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+from .._fleet_key import prepare_fleet_key
+from ..client import AsyncHttpClient
+
+
+class AsyncFleetsService:
+    def __init__(self, client: AsyncHttpClient):
+        self._client = client
+
+    async def session(self, fleet_policy_id: str | None = None) -> dict[str, Any]:
+        return await self._client.request("POST", "/v1/fleets/session", json={"fleet_policy_id": fleet_policy_id} if fleet_policy_id else {})
+
+    async def workload_enrollment_challenge(self, policy_id: str) -> dict[str, Any]:
+        return await self._client.request("POST", f"/v1/fleets/{quote(policy_id, safe='')}/workload/enrollment-challenges", json={})
+
+    async def enroll_workload(self, policy_id: str, request: dict[str, Any]) -> dict[str, Any]:
+        return await self._client.request("POST", f"/v1/fleets/{quote(policy_id, safe='')}/workload/enroll", json=request)
+
+    async def enroll_workload_local(self, policy_id: str, *, name: str, idempotency_key: str) -> dict[str, Any]:
+        public_key, sign, persist = prepare_fleet_key(policy_id, idempotency_key)
+        challenge = await self.workload_enrollment_challenge(policy_id)
+        result = await self.enroll_workload(policy_id, {"name": name, "idempotency_key": idempotency_key,
+            "public_key": public_key, "challenge_id": challenge["challenge_id"], "proof": sign(challenge["challenge"])})
+        persist(result["agent_id"])
+        return result
+
+    async def enroll_local(self, policy_id: str, *, name: str, idempotency_key: str) -> dict[str, Any]:
+        public_key, sign, persist = prepare_fleet_key(policy_id, idempotency_key)
+        challenge = await self.enrollment_challenge(policy_id)
+        result = await self.enroll(policy_id, {"name": name, "idempotency_key": idempotency_key,
+            "public_key": public_key, "challenge_id": challenge["challenge_id"], "proof": sign(challenge["challenge"])})
+        persist(result["agent_id"])
+        return result
+
+    async def list(self) -> list[dict[str, Any]]:
+        return await self._client.request("GET", "/v1/fleets")
+
+    async def list_page(self, page: int = 1, limit: int = 20) -> dict[str, Any]:
+        return await self._client.request("GET", "/v1/fleets", params={"page": page, "limit": limit})
+
+    async def get(self, policy_id: str) -> dict[str, Any]:
+        return await self._client.request("GET", f"/v1/fleets/{quote(policy_id, safe='')}")
+
+    async def membership(self, agent_id: str) -> dict[str, Any] | None:
+        return await self._client.request("GET", f"/v1/fleets/membership/{quote(agent_id, safe='')}")
+
+    async def members_page(self, policy_id: str, page: int = 1, limit: int = 20) -> dict[str, Any]:
+        return await self._client.request("GET", f"/v1/fleets/{quote(policy_id, safe='')}/members", params={"page": page, "limit": limit})
+
+    async def activate(self, definition: dict[str, Any], *, idempotency_key: str,
+                 governance_approval_id: str | None = None) -> dict[str, Any]:
+        headers = {"Idempotency-Key": idempotency_key}
+        if governance_approval_id is not None:
+            headers["X-Governance-Approval"] = governance_approval_id
+        return await self._client.request("POST", "/v1/fleets", json=definition, extra_headers=headers)
+
+    async def revise(self, policy_id: str, definition: dict[str, Any], *,
+               expected_revision: int, idempotency_key: str,
+               governance_approval_id: str | None = None) -> dict[str, Any]:
+        headers = {"If-Match": str(expected_revision), "Idempotency-Key": idempotency_key}
+        if governance_approval_id is not None:
+            headers["X-Governance-Approval"] = governance_approval_id
+        return await self._client.request("PUT", f"/v1/fleets/{quote(policy_id, safe='')}",
+                                    json=definition, extra_headers=headers)
+
+    async def members(self, policy_id: str) -> list[dict[str, Any]]:
+        return await self._client.request("GET", f"/v1/fleets/{quote(policy_id, safe='')}/members")
+
+    async def revoke_member(self, policy_id: str, agent_id: str) -> dict[str, Any]:
+        return await self._client.request("POST", f"/v1/fleets/{quote(policy_id, safe='')}/members/{quote(agent_id, safe='')}/revoke", json={})
+
+    async def revoke(self, policy_id: str) -> dict[str, Any]:
+        return await self._client.request("POST", f"/v1/fleets/{quote(policy_id, safe='')}/revoke", json={})
+
+    async def enrollment_challenge(self, policy_id: str) -> dict[str, Any]:
+        return await self._client.request("POST", f"/v1/fleets/{quote(policy_id, safe='')}/enrollment-challenges", json={})
+
+    async def enroll(self, policy_id: str, request: dict[str, Any]) -> dict[str, Any]:
+        return await self._client.request("POST", f"/v1/fleets/{quote(policy_id, safe='')}/enroll", json=request)

{getstack-1.3.0 → getstack-1.4.0}/src/getstack/_async/missions.py

@@ -12,6 +12,12 @@ class AsyncMissionsService:
     def __init__(self, client: AsyncHttpClient):
         self._client = client
 
+    async def start(self, request: dict[str, Any]) -> dict[str, Any]:
+        return await self._client.request("POST", "/v1/missions/start", json=request)
+
+    async def renew(self, mission_id: str) -> dict[str, Any]:
+        return await self._client.request("POST", f"/v1/missions/{quote(mission_id, safe='')}/renew", json={})
+
     async def open(
         self,
         intent_summary: str,
@@ -29,6 +35,12 @@ class AsyncMissionsService:
         cap_behavior: dict[str, str] | None = None,
         expires_in_seconds: int | None = None,
         parent_passport_services: list[str] | None = None,
+        fleet_policy_id: str | None = None,
+        idempotency_key: str | None = None,
+        requested_access: list[dict[str, Any]] | None = None,
+        requested_operations: list[dict[str, Any]] | None = None,
+        limits: dict[str, Any] | None = None,
+        authority_binding_ids: list[str] | None = None,
     ) -> dict[str, Any]:
         body: dict[str, Any] = {"intent_summary": intent_summary}
         if intent_services is not None:
@@ -57,6 +69,11 @@ class AsyncMissionsService:
             body["expires_in_seconds"] = expires_in_seconds
         if parent_passport_services is not None:
             body["parent_passport_services"] = parent_passport_services
+        for key, value in {"fleet_policy_id": fleet_policy_id, "idempotency_key": idempotency_key,
+            "requested_access": requested_access, "requested_operations": requested_operations,
+            "limits": limits, "authority_binding_ids": authority_binding_ids}.items():
+            if value is not None:
+                body[key] = value
         return await self._client.request("POST", "/v1/missions", json=body)
 
     async def complete(

{getstack-1.3.0 → getstack-1.4.0}/src/getstack/_async/passports.py

@@ -14,7 +14,7 @@ from contextlib import asynccontextmanager
 from typing import Any, AsyncGenerator, Awaitable, Callable
 
 from ..client import AsyncHttpClient
-from ..passports import _parse_duration, _to_passport
+from ..passports import _parse_duration, _to_passport, _delegation_scopes
 from ..proxy import ProxyResponse
 from .proxy import AsyncProxyService
 from ..types import Passport, CheckpointResult, CheckoutResult, PassportReport, ToolCall
@@ -217,6 +217,7 @@ class AsyncPassportService:
         ttl_seconds: int | None = None,
         scopes: list[dict[str, Any]] | None = None,
         authority_binding_ids: list[str] | None = None,
+        mission_ids: list[str] | None = None,
     ) -> Passport:
         """Issue a signed passport for an agent (async mirror of ``Stack``).
 
@@ -246,6 +247,8 @@ class AsyncPassportService:
             body["scopes"] = scopes
         if authority_binding_ids is not None:
             body["authority_binding_ids"] = authority_binding_ids
+        if mission_ids is not None:
+            body["mission_ids"] = mission_ids
         if ttl_seconds:
             body["ttl_seconds"] = ttl_seconds
         if intent or services:
@@ -339,12 +342,11 @@ class AsyncPassportService:
         self,
         parent_token: str,
         child_agent_id: str,
-        scopes: list[str] | None = None,
+        scopes: list[dict[str, Any]] | list[str] | None = None,
         ttl_seconds: int | None = None,
     ) -> Passport:
-        body: dict[str, Any] = {"parent_token": parent_token, "child_agent_id": child_agent_id}
-        if scopes is not None:
-            body["scopes"] = scopes
+        body: dict[str, Any] = {"parent_passport_token": parent_token, "child_agent_id": child_agent_id,
+            "scopes": _delegation_scopes(parent_token, scopes)}
         if ttl_seconds is not None:
             body["ttl_seconds"] = ttl_seconds
         return _to_passport(await self._client.post("/v1/passports/delegate", json=body))

getstack-1.4.0/src/getstack/_fleet_key.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import time
+
+from .agent_auth import _generate_keypair, _key_path, _load_stored, _persist_stored, _privkey_from_jwk, _b64url_no_pad
+
+
+def prepare_fleet_key(policy_id: str, idempotency_key: str):
+    key_id = "fleet_" + hashlib.sha256(json.dumps([policy_id, idempotency_key], separators=(",", ":")).encode()).hexdigest()
+    stored = _load_stored(key_id)
+    if stored is None:
+        _, public_key, private_key = _generate_keypair()
+        candidate = {"agent_id": key_id, "publicKey": public_key, "privateKey": private_key, "enrolled_at": time.time()}
+        path = _key_path(key_id)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        try:
+            fd = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+            with os.fdopen(fd, "w", encoding="utf8") as stream:
+                json.dump(candidate, stream)
+        except FileExistsError:
+            pass
+        stored = _load_stored(key_id)
+        for _ in range(20):
+            if stored is not None:
+                break
+            time.sleep(0.025)
+            stored = _load_stored(key_id)
+    if stored is None:
+        raise ValueError("Invalid input")
+    key = _privkey_from_jwk(stored["privateKey"])
+
+    def sign(challenge: str) -> str:
+        return _b64url_no_pad(key.sign(challenge.encode()))
+
+    def persist(agent_id: str) -> None:
+        if not re.fullmatch(r"agt_[\w-]+", agent_id):
+            raise ValueError("Invalid input")
+        _persist_stored(agent_id, {**stored, "agent_id": agent_id})
+
+    return stored["publicKey"], sign, persist

{getstack-1.3.0 → getstack-1.4.0}/src/getstack/agent_auth.py

@@ -181,9 +181,17 @@ def _load_stored(agent_id: str) -> dict | None:
 
 
 def _persist_stored(agent_id: str, payload: dict) -> None:
+    import tempfile
     path = _key_path(agent_id)
     path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(json.dumps(payload, indent=2), encoding="utf8")
+    fd, pending = tempfile.mkstemp(dir=path.parent, suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf8") as stream:
+            json.dump(payload, stream, indent=2)
+        os.replace(pending, path)
+    finally:
+        if os.path.exists(pending):
+            os.unlink(pending)
     try:
         os.chmod(path, 0o600)
     except OSError:

getstack-1.4.0/src/getstack/fleets.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+from ._fleet_key import prepare_fleet_key
+from .client import HttpClient
+
+
+class FleetsService:
+    def __init__(self, client: HttpClient):
+        self._client = client
+
+    def session(self, fleet_policy_id: str | None = None) -> dict[str, Any]:
+        return self._client.request("POST", "/v1/fleets/session", json={"fleet_policy_id": fleet_policy_id} if fleet_policy_id else {})
+
+    def workload_enrollment_challenge(self, policy_id: str) -> dict[str, Any]:
+        return self._client.request("POST", f"/v1/fleets/{quote(policy_id, safe='')}/workload/enrollment-challenges", json={})
+
+    def enroll_workload(self, policy_id: str, request: dict[str, Any]) -> dict[str, Any]:
+        return self._client.request("POST", f"/v1/fleets/{quote(policy_id, safe='')}/workload/enroll", json=request)
+
+    def enroll_workload_local(self, policy_id: str, *, name: str, idempotency_key: str) -> dict[str, Any]:
+        public_key, sign, persist = prepare_fleet_key(policy_id, idempotency_key)
+        challenge = self.workload_enrollment_challenge(policy_id)
+        result = self.enroll_workload(policy_id, {"name": name, "idempotency_key": idempotency_key,
+            "public_key": public_key, "challenge_id": challenge["challenge_id"], "proof": sign(challenge["challenge"])})
+        persist(result["agent_id"])
+        return result
+
+    def enroll_local(self, policy_id: str, *, name: str, idempotency_key: str) -> dict[str, Any]:
+        public_key, sign, persist = prepare_fleet_key(policy_id, idempotency_key)
+        challenge = self.enrollment_challenge(policy_id)
+        result = self.enroll(policy_id, {"name": name, "idempotency_key": idempotency_key,
+            "public_key": public_key, "challenge_id": challenge["challenge_id"], "proof": sign(challenge["challenge"])})
+        persist(result["agent_id"])
+        return result
+
+    def list(self) -> list[dict[str, Any]]:
+        return self._client.request("GET", "/v1/fleets")
+
+    def list_page(self, page: int = 1, limit: int = 20) -> dict[str, Any]:
+        return self._client.request("GET", "/v1/fleets", params={"page": page, "limit": limit})
+
+    def get(self, policy_id: str) -> dict[str, Any]:
+        return self._client.request("GET", f"/v1/fleets/{quote(policy_id, safe='')}")
+
+    def membership(self, agent_id: str) -> dict[str, Any] | None:
+        return self._client.request("GET", f"/v1/fleets/membership/{quote(agent_id, safe='')}")
+
+    def members_page(self, policy_id: str, page: int = 1, limit: int = 20) -> dict[str, Any]:
+        return self._client.request("GET", f"/v1/fleets/{quote(policy_id, safe='')}/members", params={"page": page, "limit": limit})
+
+    def activate(self, definition: dict[str, Any], *, idempotency_key: str,
+                 governance_approval_id: str | None = None) -> dict[str, Any]:
+        headers = {"Idempotency-Key": idempotency_key}
+        if governance_approval_id is not None:
+            headers["X-Governance-Approval"] = governance_approval_id
+        return self._client.request("POST", "/v1/fleets", json=definition, extra_headers=headers)
+
+    def revise(self, policy_id: str, definition: dict[str, Any], *,
+               expected_revision: int, idempotency_key: str,
+               governance_approval_id: str | None = None) -> dict[str, Any]:
+        headers = {"If-Match": str(expected_revision), "Idempotency-Key": idempotency_key}
+        if governance_approval_id is not None:
+            headers["X-Governance-Approval"] = governance_approval_id
+        return self._client.request("PUT", f"/v1/fleets/{quote(policy_id, safe='')}",
+                                    json=definition, extra_headers=headers)
+
+    def members(self, policy_id: str) -> list[dict[str, Any]]:
+        return self._client.request("GET", f"/v1/fleets/{quote(policy_id, safe='')}/members")
+
+    def revoke_member(self, policy_id: str, agent_id: str) -> dict[str, Any]:
+        return self._client.request("POST", f"/v1/fleets/{quote(policy_id, safe='')}/members/{quote(agent_id, safe='')}/revoke", json={})
+
+    def revoke(self, policy_id: str) -> dict[str, Any]:
+        return self._client.request("POST", f"/v1/fleets/{quote(policy_id, safe='')}/revoke", json={})
+
+    def enrollment_challenge(self, policy_id: str) -> dict[str, Any]:
+        return self._client.request("POST", f"/v1/fleets/{quote(policy_id, safe='')}/enrollment-challenges", json={})
+
+    def enroll(self, policy_id: str, request: dict[str, Any]) -> dict[str, Any]:
+        return self._client.request("POST", f"/v1/fleets/{quote(policy_id, safe='')}/enroll", json=request)

{getstack-1.3.0 → getstack-1.4.0}/src/getstack/missions.py

@@ -25,6 +25,12 @@ class MissionsService:
     def __init__(self, client: HttpClient):
         self._client = client
 
+    def start(self, request: dict[str, Any]) -> dict[str, Any]:
+        return self._client.request("POST", "/v1/missions/start", json=request)
+
+    def renew(self, mission_id: str) -> dict[str, Any]:
+        return self._client.request("POST", f"/v1/missions/{quote(mission_id, safe='')}/renew", json={})
+
     def open(
         self,
         intent_summary: str,
@@ -42,6 +48,12 @@ class MissionsService:
         cap_behavior: dict[str, str] | None = None,
         expires_in_seconds: int | None = None,
         parent_passport_services: list[str] | None = None,
+        fleet_policy_id: str | None = None,
+        idempotency_key: str | None = None,
+        requested_access: list[dict[str, Any]] | None = None,
+        requested_operations: list[dict[str, Any]] | None = None,
+        limits: dict[str, Any] | None = None,
+        authority_binding_ids: list[str] | None = None,
     ) -> dict[str, Any]:
         """Open a new mission. Returns dict with mission_id, claim_id,
         expires_at."""
@@ -72,6 +84,11 @@ class MissionsService:
             body["expires_in_seconds"] = expires_in_seconds
         if parent_passport_services is not None:
             body["parent_passport_services"] = parent_passport_services
+        for key, value in {"fleet_policy_id": fleet_policy_id, "idempotency_key": idempotency_key,
+            "requested_access": requested_access, "requested_operations": requested_operations,
+            "limits": limits, "authority_binding_ids": authority_binding_ids}.items():
+            if value is not None:
+                body[key] = value
         return self._client.request("POST", "/v1/missions", json=body)
 
     def complete(

{getstack-1.3.0 → getstack-1.4.0}/src/getstack/passports.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import re
 import time
 import threading
+import jwt
 from contextlib import contextmanager
 from typing import Any, Callable, Generator
 
@@ -31,6 +32,26 @@ def _to_passport(data: dict[str, Any]) -> Passport:
     )
 
 
+def _delegation_scopes(token: str, scopes: list[dict[str, Any]] | list[str] | None):
+    if scopes is not None and all(isinstance(scope, dict) for scope in scopes):
+        return scopes
+    # Request construction only. The API authenticates the parent Passport.
+    services = jwt.decode(token, options={"verify_signature": False, "verify_aud": False}).get("stk", {}).get("services")
+    if not isinstance(services, list):
+        raise ValueError("Invalid input")
+    selected = [service for service in services if scopes is None or service.get("service_name") in scopes]
+    if scopes is not None and any(not any(service.get("service_name") == name for service in selected) for name in scopes):
+        raise ValueError("Invalid input")
+    result = []
+    for service in selected:
+        if not isinstance(service.get("connection_id"), str) or not isinstance(service.get("scopes"), list):
+            raise ValueError("Invalid input")
+        result.append({"service_connection_id": service["connection_id"], "scopes": service["scopes"],
+            **({"constraints": service["constraints"]} if "constraints" in service else {}),
+            **({"allow_data_from": service["allow_data_from"]} if "allow_data_from" in service else {})})
+    return result
+
+
 class Mission:
     """A bounded accountability window for an agent mission.
 
@@ -246,6 +267,7 @@ class PassportService:
         ttl_seconds: int | None = None,
         scopes: list[dict[str, Any]] | None = None,
         authority_binding_ids: list[str] | None = None,
+        mission_ids: list[str] | None = None,
     ) -> Passport:
         """Issue a signed passport for an agent.
 
@@ -275,6 +297,8 @@ class PassportService:
             body["scopes"] = scopes
         if authority_binding_ids is not None:
             body["authority_binding_ids"] = authority_binding_ids
+        if mission_ids is not None:
+            body["mission_ids"] = mission_ids
         if ttl_seconds:
             body["ttl_seconds"] = ttl_seconds
         if intent or services:
@@ -369,14 +393,13 @@ class PassportService:
         self,
         parent_token: str,
         child_agent_id: str,
-        scopes: list[str] | None = None,
+        scopes: list[dict[str, Any]] | list[str] | None = None,
         ttl_seconds: int | None = None,
     ) -> Passport:
         """Delegate a passport to a child agent. Scope narrows only, max 4
         hops (enforced server-side)."""
-        body: dict[str, Any] = {"parent_token": parent_token, "child_agent_id": child_agent_id}
-        if scopes is not None:
-            body["scopes"] = scopes
+        body: dict[str, Any] = {"parent_passport_token": parent_token, "child_agent_id": child_agent_id,
+            "scopes": _delegation_scopes(parent_token, scopes)}
         if ttl_seconds is not None:
             body["ttl_seconds"] = ttl_seconds
         return _to_passport(self._client.post("/v1/passports/delegate", json=body))

getstack-1.4.0/tests/test_fleets.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+import asyncio
+import pytest
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
+
+from getstack.fleets import FleetsService
+from getstack._async.fleets import AsyncFleetsService
+from getstack.missions import MissionsService
+from getstack._async.missions import AsyncMissionsService
+from getstack.passports import PassportService
+from getstack._async.passports import AsyncPassportService
+
+
+@pytest.mark.parametrize("client_name", ["Stack", "AsyncStack"])
+def test_enrolled_worker_needs_no_operator_credentials(monkeypatch, client_name):
+    import getstack
+    from getstack import agent_auth
+    import jwt
+    def no_operator_credentials(**kwargs):
+        raise AssertionError("Enrolled worker requested operator credentials")
+    monkeypatch.setattr(getstack, "_build_static_auth", no_operator_credentials)
+    _, public, private = agent_auth._generate_keypair()
+    monkeypatch.setattr(agent_auth, "_load_stored", lambda agent_id: {"agent_id": agent_id,
+        "publicKey": public, "privateKey": private, "enrolled_at": 1})
+    client = getattr(getstack, client_name)(agent_id="agt_worker")
+    headers = client._client.auth.get_headers()
+    claims = jwt.decode(headers["Authorization"].split(" ", 1)[1], options={"verify_signature": False})
+    assert claims["sub"] == "agt_worker"
+    assert claims["aud"] == "stack:agent"
+
+
+class Capture:
+    def __init__(self):
+        self.calls = []
+
+    def request(self, method, path, **kwargs):
+        self.calls.append((method, path, kwargs))
+        return {"token": "fixture", "jti": "jti_fixture", "expires_at": "2030-01-01"}
+
+    def post(self, path, **kwargs):
+        return self.request("POST", path, **kwargs)
+
+
+class AsyncCapture(Capture):
+    async def request(self, method, path, **kwargs):
+        return super().request(method, path, **kwargs)
+
+    async def post(self, path, **kwargs):
+        return await self.request("POST", path, **kwargs)
+
+
+REQUEST = {"fleet_policy_id": "flp_fixture", "idempotency_key": "operation-123", "intent_summary": "Support update",
+    "requested_access": [{"connection_id": "scon_fixture", "scopes": ["chat:write"], "intents": [
+        {"name": "slack.post_to_channel", "params": {"channel": "C123"}}], "allow_data_from": ["github"]}],
+    "requested_operations": [{"producer": "skill", "target_id": "skl_fixture", "action": "invoke"}],
+    "limits": {"max_actions": 20, "max_concurrent_actions": 2, "max_duration_seconds": 900},
+    "authority_binding_ids": ["abn_fixture"], "expected_output_shape": {"type": "object"}}
+
+
+def test_sync_async_fleet_contract_matches():
+    sync = Capture()
+    fleets = FleetsService(sync)
+    fleets.revise("flp_one/two", {"name": "Policy"}, expected_revision=2, idempotency_key="revision-123", governance_approval_id="gvr_fixture")
+    fleets.session()
+    fleets.members("flp_one/two")
+    fleets.revoke_member("flp_one/two", "agt_one/two")
+    MissionsService(sync).start(REQUEST)
+    MissionsService(sync).renew("ms_one/two")
+    PassportService(sync).issue("agt_fixture", mission_ids=["ms_fixture"])
+    PassportService(sync).delegate("fixture", "agt_child", scopes=[{"service_connection_id": "scon_fixture", "scopes": ["read"]}])
+
+    async def run():
+        client = AsyncCapture()
+        fleets = AsyncFleetsService(client)
+        await fleets.revise("flp_one/two", {"name": "Policy"}, expected_revision=2, idempotency_key="revision-123", governance_approval_id="gvr_fixture")
+        await fleets.session()
+        await fleets.members("flp_one/two")
+        await fleets.revoke_member("flp_one/two", "agt_one/two")
+        await AsyncMissionsService(client).start(REQUEST)
+        await AsyncMissionsService(client).renew("ms_one/two")
+        await AsyncPassportService(client).issue("agt_fixture", mission_ids=["ms_fixture"])
+        await AsyncPassportService(client).delegate("fixture", "agt_child", scopes=[{"service_connection_id": "scon_fixture", "scopes": ["read"]}])
+        return client.calls
+
+    assert asyncio.run(run()) == sync.calls
+    assert sync.calls[0] == ("PUT", "/v1/fleets/flp_one%2Ftwo", {"json": {"name": "Policy"}, "extra_headers": {
+        "If-Match": "2", "Idempotency-Key": "revision-123", "X-Governance-Approval": "gvr_fixture"}})
+    assert sync.calls[4] == ("POST", "/v1/missions/start", {"json": REQUEST})
+    assert sync.calls[-2][2]["json"]["mission_ids"] == ["ms_fixture"]
+    assert sync.calls[-1][2]["json"] == {"parent_passport_token": "fixture", "child_agent_id": "agt_child", "scopes": [{"service_connection_id": "scon_fixture", "scopes": ["read"]}]}

{getstack-1.3.0 → getstack-1.4.0}/tests/test_parity.py

@@ -46,12 +46,18 @@ EXPECTED_SERVICES = [
     "partner_connect", "team", "delivery_methods",
     "detector_config",
     "pii_config",
-    "authority",
+    "authority", "fleets",
 ]
 
 # (service, method) pairs that must exist on both clients — the integration-
 # critical surface, incl. the gaps GET-244 closed.
 EXPECTED_METHODS = [
+    ("fleets", "workload_enrollment_challenge"), ("fleets", "enroll_workload"), ("fleets", "enroll_workload_local"),
+    ("fleets", "members"), ("fleets", "revoke_member"),
+    ("fleets", "session"), ("fleets", "enroll_local"),
+    ("fleets", "list"), ("fleets", "activate"), ("fleets", "revise"),
+    ("fleets", "revoke"), ("fleets", "enrollment_challenge"), ("fleets", "enroll"),
+    ("missions", "start"), ("missions", "renew"),
     ("inbound_webhooks", "set_provider_signing_secret"),
     ("services", "connect"),
     ("services", "connect_custom"),