stackshift-agent 0.1.0__tar.gz

stackshift_agent-0.1.0/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: stackshift-agent
+Version: 0.1.0
+Summary: Run an agent on StackShift: events, governed actions, StackShift calls, state and model access.
+Author-email: StackShift <support@stackshift.cloud>
+Project-URL: Homepage, https://stackshift.cloud
+Project-URL: Documentation, https://docs.stackshift.cloud
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=42
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.30; extra == "anthropic"
+Provides-Extra: openai
+Requires-Dist: openai>=1.40; extra == "openai"
+Provides-Extra: claude-agent-sdk
+Requires-Dist: claude-agent-sdk>=0.1; extra == "claude-agent-sdk"
+Provides-Extra: openai-agents
+Requires-Dist: openai-agents>=0.1; extra == "openai-agents"
+
+# stackshift-agent
+
+Write an agent that runs on StackShift. The package receives the events that wake your agent, checks that StackShift sent them, runs your handlers, and gives your code the actions, StackShift calls, state and model access an agent needs.
+
+```bash
+pip install stackshift-agent
+```
+
+Python 3.9 or newer. The Anthropic and OpenAI clients and the two adapters use packages you install yourself (`anthropic`, `openai`, `claude-agent-sdk`, `openai-agents`). None of them is needed for the rest.
+
+## A first agent
+
+```python
+from stackshift_agent import agent
+
+
+@agent.action("lookup_order")
+async def lookup_order(args):
+    return {"order_id": args["order_id"], "status": "shipped"}
+
+
+@agent.on("inbox.message")
+async def answer(event):
+    order = await lookup_order({"order_id": event.data["message"]["subject"]})
+    await agent.inbox.reply(event.data["message"], f"Your order is {order['status']}.")
+
+
+agent.start()
+```
+
+`agent.start()` listens on `PORT` (8080 when it is not set) and answers `POST /stackshift/events`. Declare `lookup_order` in the `agent:` block of `stackshift.yaml`; StackShift only lets an action run if it is declared there.
+
+## Events
+
+`agent.on(event)` runs for each event of that name: `inbox.message`, `agreement.offer_received`, `agreement.agreed`, `agreement.declined`, `agreement.expired`, `agreement.waiting_for_you`, `a2a.message`, `schedule.tick`, `webhook.received`, `approval.decided` and `budget.warning`. The handler gets an object with `type`, `id`, `at`, `data`, `untrusted` and `run_id`. Handlers can be plain or `async` functions.
+
+Each event is checked against `STACKSHIFT_EVENT_KEY` (the Ed25519 signature on the delivery) before any handler runs. Events that arrive twice are dropped by their id. A handler that raises ends the run with the outcome `failed`; a run that saved an action for approval ends `waiting`; anything else ends `done`.
+
+## Actions and approvals
+
+`agent.action(key)` wraps your function. Each call asks StackShift first, with the arguments, and StackShift answers allowed, waiting or refused under the agent's level.
+
+- **Allowed:** your function runs and its result is recorded.
+- **Refused:** the call raises `ActionRefusedError` with a reason in plain words.
+- **Waiting:** by default the call is saved in the agent's state, the run ends with the outcome `waiting`, and when the owner decides the call runs again with exactly the arguments they approved. Pass `wait=True` to hold the run for up to 55 seconds instead.
+
+Mark text your agent fetched itself with `await agent.untrusted(text, "web:example.com")`. StackShift then asks before an action built from that text does anything that matters.
+
+## Calling StackShift
+
+```python
+operation = await agent.platform.call("database.inspect", {"database_id": database_id}, reason="Check the size")
+inbox = await agent.platform.inspect("mail.agent_inboxes.get", {"inbox_id": inbox_id})
+```
+
+`call` proposes the action through the agent's connection and waits up to 55 seconds for it to settle (`wait=False` returns at once). The agent can only use the actions its owner allowed. `inspect` runs a read.
+
+`agent.inbox` has `send`, `reply`, `info` and `id`. `agent.agreements` has `list`, `inspect`, `limits`, `verify`, `wait`, `propose`, `respond`, `cancel` and `count_reply`; they work when agreements are on for the agent's inbox.
+
+## State and locks
+
+```python
+await agent.state.set("last_report", {"at": 1}, ttl_seconds=86400)
+last = await agent.state.get("last_report")
+async with agent.state.locked("nightly"):
+    ...
+```
+
+## Models
+
+`agent.anthropic()` and `agent.openai()` return the official clients, already pointed at StackShift and signed in with the agent's run token; `agent.async_anthropic()` and `agent.async_openai()` return the async ones. There is no provider key in the agent. Pass `max_tokens` on every call.
+
+## Internet access
+
+`await agent.fetch(url, method="GET", headers=None, body=None)` returns a response with `status`, `headers`, `text()` and `json()`. For a host where the owner saved a key to send on the way out, the request goes through StackShift, which adds the key. The agent never holds it.
+
+## Claude Agent SDK and OpenAI Agents SDK
+
+```python
+from stackshift_agent.adapters.claude import claude_tools
+from stackshift_agent.adapters.openai_agents import openai_tools
+
+claude = await claude_tools(agent)
+tools = await openai_tools(agent)
+```
+
+`claude_tools` returns `mcp_servers` and `allowed_tools` for `ClaudeAgentOptions`. `openai_tools` returns `FunctionTool` objects for an `Agent`. Both turn your declared actions into tools with the approval step built in. A refusal or a wait comes back to the model as text, not as an error. Call them while handling an event.
+
+## What this does and does not enforce
+
+The wrapper governs your agent's model, which is what goes wrong in practice. It is not a guard against the developer: you own the code, so you can skip it. What StackShift enforces whatever the code does: model calls through StackShift, actions on StackShift, email and agreements, and which internet addresses the agent can reach.

stackshift_agent-0.1.0/README.md

@@ -0,0 +1,91 @@
+# stackshift-agent
+
+Write an agent that runs on StackShift. The package receives the events that wake your agent, checks that StackShift sent them, runs your handlers, and gives your code the actions, StackShift calls, state and model access an agent needs.
+
+```bash
+pip install stackshift-agent
+```
+
+Python 3.9 or newer. The Anthropic and OpenAI clients and the two adapters use packages you install yourself (`anthropic`, `openai`, `claude-agent-sdk`, `openai-agents`). None of them is needed for the rest.
+
+## A first agent
+
+```python
+from stackshift_agent import agent
+
+
+@agent.action("lookup_order")
+async def lookup_order(args):
+    return {"order_id": args["order_id"], "status": "shipped"}
+
+
+@agent.on("inbox.message")
+async def answer(event):
+    order = await lookup_order({"order_id": event.data["message"]["subject"]})
+    await agent.inbox.reply(event.data["message"], f"Your order is {order['status']}.")
+
+
+agent.start()
+```
+
+`agent.start()` listens on `PORT` (8080 when it is not set) and answers `POST /stackshift/events`. Declare `lookup_order` in the `agent:` block of `stackshift.yaml`; StackShift only lets an action run if it is declared there.
+
+## Events
+
+`agent.on(event)` runs for each event of that name: `inbox.message`, `agreement.offer_received`, `agreement.agreed`, `agreement.declined`, `agreement.expired`, `agreement.waiting_for_you`, `a2a.message`, `schedule.tick`, `webhook.received`, `approval.decided` and `budget.warning`. The handler gets an object with `type`, `id`, `at`, `data`, `untrusted` and `run_id`. Handlers can be plain or `async` functions.
+
+Each event is checked against `STACKSHIFT_EVENT_KEY` (the Ed25519 signature on the delivery) before any handler runs. Events that arrive twice are dropped by their id. A handler that raises ends the run with the outcome `failed`; a run that saved an action for approval ends `waiting`; anything else ends `done`.
+
+## Actions and approvals
+
+`agent.action(key)` wraps your function. Each call asks StackShift first, with the arguments, and StackShift answers allowed, waiting or refused under the agent's level.
+
+- **Allowed:** your function runs and its result is recorded.
+- **Refused:** the call raises `ActionRefusedError` with a reason in plain words.
+- **Waiting:** by default the call is saved in the agent's state, the run ends with the outcome `waiting`, and when the owner decides the call runs again with exactly the arguments they approved. Pass `wait=True` to hold the run for up to 55 seconds instead.
+
+Mark text your agent fetched itself with `await agent.untrusted(text, "web:example.com")`. StackShift then asks before an action built from that text does anything that matters.
+
+## Calling StackShift
+
+```python
+operation = await agent.platform.call("database.inspect", {"database_id": database_id}, reason="Check the size")
+inbox = await agent.platform.inspect("mail.agent_inboxes.get", {"inbox_id": inbox_id})
+```
+
+`call` proposes the action through the agent's connection and waits up to 55 seconds for it to settle (`wait=False` returns at once). The agent can only use the actions its owner allowed. `inspect` runs a read.
+
+`agent.inbox` has `send`, `reply`, `info` and `id`. `agent.agreements` has `list`, `inspect`, `limits`, `verify`, `wait`, `propose`, `respond`, `cancel` and `count_reply`; they work when agreements are on for the agent's inbox.
+
+## State and locks
+
+```python
+await agent.state.set("last_report", {"at": 1}, ttl_seconds=86400)
+last = await agent.state.get("last_report")
+async with agent.state.locked("nightly"):
+    ...
+```
+
+## Models
+
+`agent.anthropic()` and `agent.openai()` return the official clients, already pointed at StackShift and signed in with the agent's run token; `agent.async_anthropic()` and `agent.async_openai()` return the async ones. There is no provider key in the agent. Pass `max_tokens` on every call.
+
+## Internet access
+
+`await agent.fetch(url, method="GET", headers=None, body=None)` returns a response with `status`, `headers`, `text()` and `json()`. For a host where the owner saved a key to send on the way out, the request goes through StackShift, which adds the key. The agent never holds it.
+
+## Claude Agent SDK and OpenAI Agents SDK
+
+```python
+from stackshift_agent.adapters.claude import claude_tools
+from stackshift_agent.adapters.openai_agents import openai_tools
+
+claude = await claude_tools(agent)
+tools = await openai_tools(agent)
+```
+
+`claude_tools` returns `mcp_servers` and `allowed_tools` for `ClaudeAgentOptions`. `openai_tools` returns `FunctionTool` objects for an `Agent`. Both turn your declared actions into tools with the approval step built in. A refusal or a wait comes back to the model as text, not as an error. Call them while handling an event.
+
+## What this does and does not enforce
+
+The wrapper governs your agent's model, which is what goes wrong in practice. It is not a guard against the developer: you own the code, so you can skip it. What StackShift enforces whatever the code does: model calls through StackShift, actions on StackShift, email and agreements, and which internet addresses the agent can reach.

stackshift_agent-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "stackshift-agent"
+version = "0.1.0"
+description = "Run an agent on StackShift: events, governed actions, StackShift calls, state and model access."
+readme = "README.md"
+requires-python = ">=3.9"
+authors = [{name = "StackShift", email = "support@stackshift.cloud"}]
+classifiers = ["Programming Language :: Python :: 3"]
+dependencies = ["cryptography>=42"]
+
+[project.optional-dependencies]
+anthropic = ["anthropic>=0.30"]
+openai = ["openai>=1.40"]
+claude-agent-sdk = ["claude-agent-sdk>=0.1"]
+openai-agents = ["openai-agents>=0.1"]
+
+[project.urls]
+Homepage = "https://stackshift.cloud"
+Documentation = "https://docs.stackshift.cloud"
+
+[tool.setuptools]
+packages = ["stackshift_agent", "stackshift_agent.adapters"]

stackshift_agent-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

stackshift_agent-0.1.0/stackshift_agent/__init__.py

@@ -0,0 +1,32 @@
+from .actions import Actions
+from .agent import AgentTool, StackShiftAgent, create_agent
+from .agreements import Agreements
+from .errors import ActionRefusedError, ActionWaitingError, PlatformCallError, StackShiftAgentError
+from .http import Response
+from .inbox import Inbox, address_of
+from .platform import Platform
+from .run import AgentEvent, ApprovalDecided
+from .state import Lock, State
+
+agent = create_agent()
+
+__all__ = [
+    "Actions",
+    "ActionRefusedError",
+    "ActionWaitingError",
+    "AgentEvent",
+    "AgentTool",
+    "ApprovalDecided",
+    "Agreements",
+    "Inbox",
+    "Lock",
+    "Platform",
+    "PlatformCallError",
+    "Response",
+    "StackShiftAgent",
+    "StackShiftAgentError",
+    "State",
+    "address_of",
+    "agent",
+    "create_agent",
+]

stackshift_agent-0.1.0/stackshift_agent/actions.py

@@ -0,0 +1,104 @@
+from __future__ import annotations
+
+import functools
+import inspect
+import json
+import uuid
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable
+from urllib.parse import quote
+
+from .api import Api
+from .errors import ActionRefusedError, ActionWaitingError, StackShiftAgentError
+from .run import current_run
+from .state import State
+
+PENDING_SECONDS = 8 * 24 * 3600
+OUTPUT_LIMIT = 60_000
+SUMMARY_LIMIT = 240
+WAIT_SECONDS = 55
+
+
+@dataclass
+class Entry:
+    key: str
+    run: Callable[[Any], Any]
+
+
+class Actions:
+    def __init__(self, api: Api, state: State) -> None:
+        self._api = api
+        self._state = state
+        self._entries: dict[str, Entry] = {}
+
+    def register(self, key: str, run: Callable[[Any], Any], wait: bool = False) -> Callable[[Any], Awaitable[Any]]:
+        if key in self._entries:
+            raise StackShiftAgentError(f"The action {key} is already registered.", code="action_registered")
+        self._entries[key] = Entry(key, run)
+
+        async def admitted(args: Any = None) -> Any:
+            return await self._admit_and_run(key, args, wait)
+
+        return functools.wraps(run)(admitted)
+
+    def has(self, key: str) -> bool:
+        return key in self._entries
+
+    async def invoke(self, key: str, args: Any, wait: bool = False) -> Any:
+        if key not in self._entries:
+            raise StackShiftAgentError(f"There is no action {key} in this agent.", status=404, code="action_unknown")
+        return await self._admit_and_run(key, args, wait)
+
+    async def approved(self, admission_id: str, key: str, args: Any) -> bool:
+        parts = key.split(".")
+        entry = self._entries.get(".".join(parts[2:]) if parts[0] == "custom" and len(parts) >= 3 else key)
+        if entry is None:
+            return False
+        await self._state.delete(_pending_key(admission_id))
+        await self._execute(entry, admission_id, args)
+        return True
+
+    async def forget(self, admission_id: str) -> None:
+        await self._state.delete(_pending_key(admission_id))
+
+    async def _admit_and_run(self, key: str, args: Any, wait: bool) -> Any:
+        context = current_run.get()
+        if context is None:
+            raise StackShiftAgentError("Actions run while the agent handles an event.", code="no_run")
+        admission = await self._api.request(
+            "POST",
+            f"/agents/self/actions/{quote(key, safe='')}/admit",
+            {"run_id": context.run_id, "arguments": args if args is not None else {}, "correlation_id": str(uuid.uuid4())},
+        )
+        if admission["decision"] == "waiting" and wait:
+            admission = await self._api.request("GET", f"/agents/self/admissions/{admission['admission_id']}/wait", query={"seconds": WAIT_SECONDS}) or admission
+        if admission["decision"] == "refused":
+            raise ActionRefusedError(key, admission.get("reason", ""), admission.get("message", ""), admission.get("untrusted"))
+        if admission["decision"] == "waiting":
+            await self._state.set(
+                _pending_key(admission["admission_id"]),
+                {"key": key, "arguments": args, "admission_id": admission["admission_id"]},
+                ttl_seconds=PENDING_SECONDS,
+            )
+            context.waiting = True
+            raise ActionWaitingError(key, admission["admission_id"], admission.get("approval_id"), admission.get("message"))
+        return await self._execute(self._entries[key], admission["admission_id"], args)
+
+    async def _execute(self, entry: Entry, admission_id: str, args: Any) -> Any:
+        try:
+            result = entry.run(args)
+            if inspect.isawaitable(result):
+                result = await result
+        except Exception as failure:
+            await self._report(admission_id, "failed", str(failure), "")
+            raise
+        output = result if isinstance(result, str) else json.dumps(result)
+        await self._report(admission_id, "succeeded", output[:SUMMARY_LIMIT], output[:OUTPUT_LIMIT])
+        return result
+
+    async def _report(self, admission_id: str, status: str, summary: str, output: str) -> None:
+        await self._api.request("POST", f"/agents/self/admissions/{admission_id}/result", {"status": status, "summary": summary[:SUMMARY_LIMIT], "output": output})
+
+
+def _pending_key(admission_id: str) -> str:
+    return f"pending:{admission_id}"

stackshift_agent-0.1.0/stackshift_agent/adapters/claude.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..agent import StackShiftAgent
+from ..models import load
+
+
+async def claude_tools(agent: StackShiftAgent, *, server_name: str = "stackshift", sdk: Any = None) -> dict[str, Any]:
+    module = sdk or load("claude_agent_sdk", "Install claude-agent-sdk to use the Claude adapter.")
+    tools = await agent.tools()
+    definitions = []
+    for definition in tools:
+        definitions.append(_define(module, definition))
+    return {
+        "mcp_servers": {server_name: module.create_sdk_mcp_server(name=server_name, tools=definitions)},
+        "allowed_tools": [f"mcp__{server_name}__{definition.name}" for definition in tools],
+    }
+
+
+def _define(module: Any, definition: Any) -> Any:
+    async def handler(arguments: dict[str, Any]) -> dict[str, Any]:
+        return {"content": [{"type": "text", "text": await definition.execute(arguments)}]}
+
+    annotations = module.ToolAnnotations(readOnlyHint=definition.read_only)
+    return module.tool(definition.name, definition.description, definition.parameters, annotations=annotations)(handler)

stackshift_agent-0.1.0/stackshift_agent/adapters/openai_agents.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from ..agent import StackShiftAgent
+from ..models import load
+
+
+async def openai_tools(agent: StackShiftAgent, *, sdk: Any = None) -> list[Any]:
+    module = sdk or load("agents", "Install openai-agents to use the OpenAI Agents adapter.")
+    return [_define(module, definition) for definition in await agent.tools()]
+
+
+def _define(module: Any, definition: Any) -> Any:
+    async def invoke(_: Any, arguments: str) -> str:
+        return await definition.execute(json.loads(arguments) if arguments else {})
+
+    return module.FunctionTool(
+        name=definition.name,
+        description=definition.description,
+        params_json_schema=definition.parameters,
+        on_invoke_tool=invoke,
+        strict_json_schema=False,
+    )

stackshift_agent-0.1.0/stackshift_agent/agent.py

@@ -0,0 +1,250 @@
+from __future__ import annotations
+
+import asyncio
+import inspect
+import json
+import threading
+from dataclasses import dataclass
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Any, Awaitable, Callable, Mapping
+
+from .actions import Actions
+from .agreements import Agreements
+from .api import Api
+from .config import Config, resolve_config
+from .egress import fetch as egress_fetch
+from .errors import ActionWaitingError, StackShiftAgentError
+from .http import Response
+from .inbox import Inbox
+from .models import anthropic_client, openai_client
+from .platform import Platform
+from .run import AgentEvent, ApprovalDecided, RunContext, current_run
+from .state import State
+from .tokens import TokenStore
+from .verify import verify_delivery
+
+EVENT_PATH = "/stackshift/events"
+BODY_LIMIT = 4 << 20
+SEEN_LIMIT = 5000
+SEEN_SECONDS = 8 * 24 * 3600
+
+Handler = Callable[[AgentEvent], Any]
+
+
+@dataclass
+class AgentTool:
+    name: str
+    description: str
+    parameters: dict[str, Any]
+    read_only: bool
+    execute: Callable[[dict[str, Any]], Awaitable[str]]
+
+
+class StackShiftAgent:
+    def __init__(self, **options: Any) -> None:
+        self.config: Config = resolve_config(**options)
+        self._tokens = TokenStore(self.config.token_file)
+        self._api = Api(self.config, self._tokens)
+        self.state = State(self._api)
+        self.platform = Platform(self.config, self._tokens)
+        self._actions = Actions(self._api, self.state)
+        self.inbox = Inbox(self.platform, self.self_)
+        self.agreements = Agreements(self.platform, self.inbox.id)
+        self._handlers: dict[str, list[Handler]] = {}
+        self._seen: dict[str, None] = {}
+        self._running: set[str] = set()
+        self._guard = threading.Lock()
+        self._self: dict[str, Any] | None = None
+
+    def on(self, event: str, handler: Handler | None = None) -> Any:
+        def register(function: Handler) -> Handler:
+            self._handlers.setdefault(event, []).append(function)
+            return function
+
+        return register if handler is None else register(handler)
+
+    def action(self, key: str, run: Callable[[Any], Any] | None = None, *, wait: bool = False) -> Any:
+        if run is not None:
+            return self._actions.register(key, run, wait)
+        return lambda function: self._actions.register(key, function, wait)
+
+    async def self_(self) -> dict[str, Any]:
+        if self._self is None:
+            self._self = await self._api.request("GET", "/agents/self")
+        return self._self
+
+    async def tools(self) -> list[AgentTool]:
+        declared = (await self.self_())["actions"]
+        return [
+            AgentTool(
+                name=item["key"],
+                description=item["summary"],
+                parameters=item["input_schema"],
+                read_only=item["tier"] == "read",
+                execute=self._tool_runner(item["key"]),
+            )
+            for item in declared
+            if self._actions.has(item["key"])
+        ]
+
+    async def untrusted(self, text: str, source: str) -> str:
+        context = current_run.get()
+        if context is None:
+            raise StackShiftAgentError("Mark text as untrusted while the agent handles an event.", code="no_run")
+        await self._api.request("POST", "/agents/self/untrusted", {"run_id": context.run_id, "source": source, "text": text})
+        return text
+
+    async def fetch(self, url: str, *, method: str = "GET", headers: Mapping[str, str] | None = None, body: bytes | str | None = None) -> Response:
+        return await egress_fetch(self.config, url, method=method, headers=headers, body=body)
+
+    def anthropic(self) -> Any:
+        return anthropic_client(self.config, self._tokens, asynchronous=False)
+
+    def async_anthropic(self) -> Any:
+        return anthropic_client(self.config, self._tokens, asynchronous=True)
+
+    def openai(self) -> Any:
+        return openai_client(self.config, self._tokens, asynchronous=False)
+
+    def async_openai(self) -> Any:
+        return openai_client(self.config, self._tokens, asynchronous=True)
+
+    def serve(self) -> ThreadingHTTPServer:
+        if not self.config.event_key:
+            raise StackShiftAgentError("STACKSHIFT_EVENT_KEY is not set. StackShift sets it when the agent runs.", code="event_key_missing")
+        agent = self
+
+        class Events(BaseHTTPRequestHandler):
+            def do_GET(self) -> None:
+                self._send(200, {"ok": True}) if self.path == "/healthz" else self._send(404, {"error": "Not found."})
+
+            def do_POST(self) -> None:
+                if self.path != EVENT_PATH:
+                    return self._send(404, {"error": "Not found."})
+                length = int(self.headers.get("Content-Length") or 0)
+                if length > BODY_LIMIT:
+                    return self._send(413, {"error": "The event is too large."})
+                headers = {name.lower(): value for name, value in self.headers.items()}
+                try:
+                    status, body = asyncio.run(agent.deliver(headers, self.rfile.read(length)))
+                except Exception as failure:
+                    status, body = 500, {"error": str(failure)}
+                self._send(status, body)
+
+            def _send(self, status: int, body: dict[str, Any]) -> None:
+                payload = json.dumps(body).encode()
+                self.send_response(status)
+                self.send_header("Content-Type", "application/json")
+                self.send_header("Content-Length", str(len(payload)))
+                self.end_headers()
+                self.wfile.write(payload)
+
+            def log_message(self, *_: Any) -> None:
+                return
+
+        return ThreadingHTTPServer(("", self.config.port), Events)
+
+    def start(self) -> None:
+        self.serve().serve_forever()
+
+    async def deliver(self, headers: Mapping[str, str], body: bytes) -> tuple[int, dict[str, Any]]:
+        if not verify_delivery(self.config.event_key, headers, body, self.config.now()):
+            return 401, {"error": "The event was not signed by StackShift."}
+        token = headers.get("x-stackshift-agent-token")
+        run_id = headers.get("x-stackshift-run")
+        event = _parse_event(body, run_id or "")
+        if not token or not run_id or event is None:
+            return 400, {"error": "The event is missing its token, run or body."}
+        with self._guard:
+            if event.id in self._seen:
+                return 200, {"outcome": "done"}
+            if event.id in self._running:
+                return 503, {"error": "This event is already running."}
+            self._running.add(event.id)
+        try:
+            await asyncio.to_thread(self._tokens.set, token)
+            return 200, await self._run(event)
+        finally:
+            with self._guard:
+                self._running.discard(event.id)
+
+    async def _run(self, event: AgentEvent) -> dict[str, Any]:
+        if await self._stored(event.id):
+            return {"outcome": "done"}
+        context = RunContext(run_id=event.run_id, event=event)
+        reset = current_run.set(context)
+        error: str | None = None
+        try:
+            await self._dispatch(event)
+            outcome = "waiting" if context.waiting else "done"
+        except ActionWaitingError:
+            outcome = "waiting"
+        except Exception as failure:
+            outcome, error = "failed", str(failure)
+        finally:
+            current_run.reset(reset)
+        if outcome != "failed":
+            await self._remember(event.id)
+        return {"outcome": outcome} if error is None else {"outcome": outcome, "error": error}
+
+    async def _dispatch(self, event: AgentEvent) -> None:
+        if event.type == "approval.decided":
+            data: ApprovalDecided = event.data
+            if data["decision"] == "approved":
+                await self._actions.approved(data["admission_id"], data["action_key"], data["arguments"])
+            else:
+                await self._actions.forget(data["admission_id"])
+        for handler in self._handlers.get(event.type, []):
+            result = handler(event)
+            if inspect.isawaitable(result):
+                await result
+
+    async def _stored(self, event_id: str) -> bool:
+        try:
+            return await self.state.get(f"event:{event_id}") is not None
+        except StackShiftAgentError:
+            return False
+
+    async def _remember(self, event_id: str) -> None:
+        with self._guard:
+            self._seen[event_id] = None
+            if len(self._seen) > SEEN_LIMIT:
+                del self._seen[next(iter(self._seen))]
+        try:
+            await self.state.set(f"event:{event_id}", True, ttl_seconds=SEEN_SECONDS)
+        except StackShiftAgentError:
+            return
+
+    def _tool_runner(self, key: str) -> Callable[[dict[str, Any]], Awaitable[str]]:
+        async def run(arguments: dict[str, Any]) -> str:
+            try:
+                result = await self._actions.invoke(key, arguments)
+            except ActionWaitingError:
+                return f"{key} needs the owner's approval. It is saved and runs once the owner approves. Stop working on this for now."
+            except StackShiftAgentError as failure:
+                return f"{key} was not done: {failure}"
+            return result if isinstance(result, str) else json.dumps(result)
+
+        return run
+
+
+def _parse_event(body: bytes, run_id: str) -> AgentEvent | None:
+    try:
+        parsed = json.loads(body)
+    except ValueError:
+        return None
+    if not isinstance(parsed, dict) or not parsed.get("event") or not parsed.get("id"):
+        return None
+    return AgentEvent(
+        type=parsed["event"],
+        id=parsed["id"],
+        agent=parsed.get("agent", ""),
+        at=parsed.get("at", ""),
+        data=parsed.get("data"),
+        untrusted=parsed.get("untrusted") or [],
+        run_id=run_id,
+    )
+
+
+def create_agent(**options: Any) -> StackShiftAgent:
+    return StackShiftAgent(**options)