solidx-agenthub-runtime 0.1.0__tar.gz

solidx_agenthub_runtime-0.1.0/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: solidx-agenthub-runtime
+Version: 0.1.0
+Summary: SolidX AgentHub agent loop and runtime
+Requires-Python: >=3.11
+Requires-Dist: mini-swe-agent<2.5,>=2.4.6
+Requires-Dist: litellm
+Requires-Dist: pydantic>=2
+Requires-Dist: pyyaml
+Requires-Dist: fastapi
+Requires-Dist: uvicorn[standard]
+Requires-Dist: sqlalchemy<2.1,>=2
+Requires-Dist: psycopg2-binary
+Requires-Dist: cryptography
+Requires-Dist: requests
+Requires-Dist: boto3
+Requires-Dist: typer
+Requires-Dist: mcp<2.3,>=2.2
+Requires-Dist: httpx
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: httpx; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: build; extra == "dev"

solidx_agenthub_runtime-0.1.0/README.md

@@ -0,0 +1,267 @@
+# SolidX AgentHub runtime
+
+Python agent loop and single-host runtime for SolidX-configured agents. See
+[`docs/technical-design.md`](docs/technical-design.md) for the agreed behavior
+and [`docs/module-contract.md`](docs/module-contract.md) for the SolidX-owned
+schema and IAM integration points. Tables are SolidX Core's `ss_agent_*`
+entities; the runtime only reads and writes rows and never changes the schema.
+
+## Development
+
+The PyPI release procedure (stable from `main`, beta/RC from `dev`) is documented in
+[`docs/RELEASE.md`](docs/RELEASE.md) and implemented in [`.github/workflows/release.yml`](.github/workflows/release.yml).
+Configure this repository's PyPI Trusted Publisher and GitHub environments before the first release.
+
+Requires Python 3.11+.
+The mini-SWE-agent dependency is pinned to the 2.4.x line exercised by the
+contract and runtime tests; upgrade only after rerunning those tests.
+
+```sh
+python -m venv .venv
+.venv/bin/python -m pip install -e '.[dev]'
+.venv/bin/python -m pytest -q
+.venv/bin/python -m ruff check src tests
+PYTHONPATH=src .venv/bin/python scripts/load_smoke.py
+```
+
+The disk harness requires no SolidX database. Copy
+`examples/osv-review/secrets.env.example` to `secrets.env` (gitignored), set
+your local model key, and update `llm.json` with your own compatible model
+endpoint/model name. Run:
+
+```sh
+agenthub-runtime run examples/osv-review "Check APP-2026-00123"
+agenthub-runtime serve --config-source disk --path examples/osv-review --port 9100
+```
+
+Disk `serve` is **unauthenticated and loopback-only**. `POST /api/sessions`
+returns a session ID and `/ws/sessions/{id}` path. The WebSocket accepts
+`message`, `human_response`, `cancel`, and `end_session` actions. Its event
+stream can be used to adapt the separately maintained admin chat UI.
+
+For database mode, SolidX Core must supply the `ss_agent_*` tables (and the
+settings documented in `docs/module-contract.md`). The manager requires `DATABASE_URL`,
+`SOLIDX_API_BASE_URL`, and `APP_ENCRYPTION_KEY` (to resolve linked secrets).
+`AGENTHUB_ADMIN_ROLES` defaults to `Admin`; set it to the comma-separated
+SolidX role names used by your administrators if they differ. Put settings in
+`.env` (copy `.env.example`; gitignored) or the OS environment, which wins. The manager
+removes `APP_ENCRYPTION_KEY` from its child environment. Start the manager with
+`agenthub-runtime manager --port 9000`. It spawns DB-mode `serve` processes
+on allocated ports. `AGENTHUB_BIND_HOST` and `AGENTHUB_PUBLIC_HOST` must be
+configured for the intended network path; default bindings use loopback.
+
+The TypeScript client lives in `sdk/typescript/`; it uses built-in `fetch` and
+exposes `agents(id).run`, `jobs.get/wait/cancel`, and
+`humanRequests.answer`. Build it with `npm run build` in that directory once
+TypeScript is available.
+
+## Test an agent asynchronously
+
+This exercises the manager job API. The manager validates a SolidX JWT,
+enqueues the job, and spawns a runtime process if none is ready. Do not start
+`serve` yourself. Seed the example agent with `scripts/setup_ai_news_agent.py`
+(it only inserts rows into Core's tables, which must already exist; it is safe
+to re-run). Agents are addressed by Core's numeric id, which the script prints
+(or `SELECT id FROM ss_agent_registry WHERE name = 'ai-news'`). The caller must
+already have a role linked in `ss_agent_role` for the agent: insert
+`(agent_registry_id, role_metadata_id)` with the caller's SolidX role id before
+running the example below.
+
+Use three terminals. The SolidX API can be any SolidX consuming project.
+
+1. Start that project's API, and leave it running:
+
+```sh
+cd /path/to/any-solidx-consuming-project/solid-api
+npm run solidx:dev
+```
+
+Wait until it prints that the server started. Use that port below. These
+examples assume `http://localhost:3000`.
+
+2. Start the manager against the same project's database. Take the user,
+password, host, port, and database name from that project's `solid-api/.env`
+(`DEFAULT_DATABASE_*`), and `SOLIDX_API_BASE_URL` from the same setting (or `BASE_URL` for older projects).
+
+```sh
+export DATABASE_URL='postgresql://USER:PASSWORD@localhost:5432/DATABASE'
+export SOLIDX_API_BASE_URL='http://localhost:3000'
+
+cd ~/Documents/Codes/solidx-agenthub-runtime
+.venv/bin/agenthub-runtime manager --port 9000
+```
+
+In a third terminal, confirm the manager:
+
+```sh
+curl -s http://127.0.0.1:9000/health
+```
+
+Expect `{"status":"ready"}`.
+
+3. Log in as a user allowed to run the agent and keep the access token:
+
+```sh
+curl -s http://127.0.0.1:3000/api/iam/authenticate \
+  -H 'Content-Type: application/json' \
+  -d '{"username":"YOUR_USERNAME","password":"YOUR_PASSWORD"}'
+```
+
+```sh
+export TOKEN='paste-the-access-token'
+```
+
+4. Create the job. This call also starts the agent process. Replace `AGENT_ID`
+with the numeric id of the `ai-news` agent:
+
+```sh
+curl -s http://127.0.0.1:9000/api/agents/AGENT_ID/jobs \
+  -H "Authorization: Bearer $TOKEN" \
+  -H 'Content-Type: application/json' \
+  -d '{"task":"Fetch AI news from the last 24 hours and summarize the titles and links."}'
+```
+
+A 401 means the token was rejected. A 403 means this user has no role linked to
+the agent. Save `jobId`, then confirm the spawned process:
+
+```sh
+curl -s http://127.0.0.1:9100/health
+```
+
+Expect `{"status":"ready","agent":AGENT_ID}`.
+
+5. Poll until the job finishes:
+
+```sh
+curl -s http://127.0.0.1:9000/api/jobs/JOB_ID \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+`queued` or `running` means it is still working. `succeeded` puts the Hacker
+News summary in `result`. `failed` puts the reason in `error`.
+
+`result` is the `{"widgetName","data"}` envelope the model replies with; the
+summary text is in `data`.
+
+### Use an API key instead of a JWT
+
+`POST /api/agents/AGENT_ID/jobs` and the job-status call also accept a Solid API
+key in the `solidx-api-key` header. The manager exchanges it at IAM for the user
+and an access token, and the job runs as that user.
+
+```sh
+export API_KEY='paste-the-solid-api-key'
+
+curl -i http://127.0.0.1:9000/api/agents/AGENT_ID/jobs \
+  -H "solidx-api-key: $API_KEY" \
+  -H 'Content-Type: application/json' \
+  -d '{"task":"What can you do."}'
+
+curl -i http://127.0.0.1:9000/api/jobs/JOB_ID \
+  -H "solidx-api-key: $API_KEY"
+```
+
+`-d` makes the request a POST, and `-i` prints the status line so a 401 or 403 is
+visible. `POST /api/agents/AGENT_ID/webhook` takes the same body but accepts only
+an API key, never a JWT.
+
+## Test an agent interactively
+
+Interactive chat follows the SolidX agent project's contract, so the same chat UI works against both
+backends. The manager only signs the user in; the chat itself runs on the agent process.
+
+1. **Sign in (manager).** `POST /api/agent/api-keys/me` with `{"apiKey": "<Solid API key>", "agentId": <id>}`.
+   The manager checks the key with SolidX once, checks the user has a role linked to the agent, starts
+   (or picks) a process, hands it the entry for a new `agentToken`, and replies
+   `{"agentToken", "user": {"id", "username"}, "wsUrl", "httpUrl"}`. The API key never leaves the server.
+2. **Chat (process, WebSocket).** Connect to `wsUrl` (`.../ws/agent`). Every frame carries `agentToken`:
+   `start_session`, `resume_session` (with `session_id`), `message` (`session_id`, `content`),
+   `cancel`, `end_session`, `update_session` (acknowledged only) and `human_response`
+   (`session_id`, `request_id`, `choice`, `text`). The process answers with `session_started`,
+   the agent's events (`UserMessage`, `ToolCalling`, `LlmToken`, `TurnCompleteEvent`, ...), `turn_complete`,
+   `execution_cancelled`, `session_ended` and `error`.
+3. **Sessions (process, REST on `httpUrl`)**, each with `Authorization: Bearer <agentToken>`:
+   `GET /api/agent/sessions/history`, `GET /api/agent/sessions/{id}/messages?page=&page_size=`,
+   `DELETE /api/agent/sessions/{id}`, `DELETE /api/agent/api-keys/me` (sign out: forgets the token), plus the stand-ins `GET /api/agent/providers` and
+   `GET /api/agent/providers/{id}/models`.
+
+After sign-in the browser never calls the manager again. If a process restarts, its entries are gone:
+sign in again and resume the conversation with `resume_session` (it restores from the last checkpoint).
+
+Settings: the manager needs `AGENTHUB_MANAGER_INTERNAL_TOKEN` (at least 32 random bytes; it signs the
+handover to the process). `AGENTHUB_PUBLIC_HOST` and `AGENTHUB_PUBLIC_WS_SCHEME` build `wsUrl`, and a browser
+must be able to reach the process ports (`AGENTHUB_PORT_RANGE`). Browsers on `localhost` or `127.0.0.1` (any port) may
+always call the manager (sign-in) and the processes; `AGENTHUB_CORS_ORIGINS` (comma separated) adds other UI
+origins. A token is forgotten after `AGENTHUB_AGENT_TOKEN_IDLE_SECONDS` (default 1800) without use.
+
+With the manager running, `examples/ai-news-chat/index.html` is a small client for this, served at
+`http://127.0.0.1:9000/chat/`. Enter the agent's numeric id and a Solid API key.
+
+## Use an agent from an MCP client
+
+The MCP bridge lets Codex, Claude Code, Cursor, Copilot, VS Code, or Claude
+Desktop use an AgentHub agent's instructions, skills, and tools. The client
+reasons with your own subscription; AgentHub calls no model in this mode, so
+the agent does not need a configured model. Details are in
+`docs/technical-design.md` §19.
+
+Start the manager with `AGENTHUB_MANAGER_INTERNAL_TOKEN` set to at least 32
+random bytes (for example `openssl rand -hex 32`). Set
+`AGENTHUB_MCP_PUBLIC_URL` and `AGENTHUB_MCP_ALLOWED_HOSTS` if clients reach
+the manager through a name other than `127.0.0.1:9000`. Then list your agents
+and get a client config:
+
+```sh
+export AGENTHUB_MCP_TOKEN="$TOKEN"   # SolidX JWT or API key
+curl -s http://127.0.0.1:9000/api/mcp/agents -H "Authorization: Bearer $TOKEN"
+curl -s "http://127.0.0.1:9000/api/mcp/agents/AGENT_ID/client-config?client=codex" \
+  -H "Authorization: Bearer $TOKEN"
+```
+
+For Codex, the returned config is:
+
+```toml
+[mcp_servers.agenthub]
+url = "http://127.0.0.1:9000/mcp/agents/AGENT_ID"
+bearer_token_env_var = "AGENTHUB_MCP_TOKEN"
+tool_timeout_sec = 150
+```
+
+Keep tokens in environment variables, not in checked-in config files. Tools
+that need approval either prompt in the client (clients that support MCP
+elicitation on protocol 2026-07-28) or return a `request_id`: approve it with
+`POST /api/human-requests/{id}/answer`, then ask the client to call
+`agenthub_get_request_result`. Every MCP request is audited in
+`ss_mcp_audit_log`; read your session's log with
+`GET /api/sessions/{id}/mcp-calls`.
+
+For a disk agent without SolidX, run an unauthenticated local server:
+
+```sh
+agenthub-runtime mcp examples/osv-review                         # stdio
+agenthub-runtime mcp examples/osv-review --transport http --port 9200
+```
+
+For stdio clients, configure the command `agenthub-runtime` with arguments
+`mcp /absolute/path/to/agent`.
+
+## Deployment boundaries
+
+For third-party JavaScript/React chat embedding, server-side token exchange, hosting requirements
+and manual validation steps, see [Agent embedding](docs/AGENT-EMBEDDING.md).
+
+- The SolidX module owns registry CRUD, tables/migrations, UI integration, and
+  `config_version` bump triggers. This runtime does not create production tables.
+- Custom tools run in the agent process with its DB access and linked secrets.
+  The AST guard and isolated *validation subprocess* are **not a sandbox**.
+  Link only reviewed tools. A timed-out synchronous tool may continue running
+  in a worker thread.
+- Plain model keys in the SolidX settings row, direct process WebSockets,
+  outbound `curl`/HTTP, and single-host placement remain first-cut limitations.
+- `docs/module-contract.md` includes settings-table and SolidX REST path
+  assumptions that need confirmation with the separate module before a
+  production integration test. No real credentials or provider calls are used
+  by the tests.
+- `scripts/load_smoke.py` measures local RSS and 4/8/16/32 concurrent mock
+  turns; it does not replace Postgres, real-provider, cold-spawn, or callback
+  load tests in the technical design.

solidx_agenthub_runtime-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "solidx-agenthub-runtime"
+version = "0.1.0"
+description = "SolidX AgentHub agent loop and runtime"
+requires-python = ">=3.11"
+dependencies = [
+  "mini-swe-agent>=2.4.6,<2.5",
+  "litellm",
+  "pydantic>=2",
+  "pyyaml",
+  "fastapi",
+  "uvicorn[standard]",
+  "sqlalchemy>=2,<2.1",
+  "psycopg2-binary",
+  "cryptography",
+  "requests",
+  "boto3",
+  "typer",
+  "mcp>=2.2,<2.3",
+  "httpx",
+]
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-asyncio", "httpx", "ruff", "build"]
+
+[project.scripts]
+agenthub-runtime = "agenthub.cli:app"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+agenthub = ["builtin_catalog.json"]
+"agenthub.skills" = ["builtin/*.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F"]

solidx_agenthub_runtime-0.1.0/setup.cfg

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

solidx_agenthub_runtime-0.1.0/src/agenthub/__init__.py

@@ -0,0 +1,3 @@
+"""SolidX AgentHub runtime."""
+
+__version__ = "0.1.0"

solidx_agenthub_runtime-0.1.0/src/agenthub/bridge/__init__.py

@@ -0,0 +1 @@
+"""LLM-free, session-scoped MCP access to AgentHub tools."""

solidx_agenthub_runtime-0.1.0/src/agenthub/bridge/audit.py

@@ -0,0 +1,72 @@
+"""Bounded, best-effort audit writes; never capture HTTP streams."""
+
+import asyncio
+import json
+import logging
+import os
+from datetime import timedelta
+
+from sqlalchemy import delete
+
+from agenthub.persistence.models import McpAuditLog, naive_now
+
+
+logger = logging.getLogger(__name__)
+
+
+def payload(value):
+    if value is None or os.getenv("AGENTHUB_MCP_AUDIT_PAYLOADS", "true").lower() != "true":
+        return None
+    text = value if isinstance(value, str) else json.dumps(value, default=str)
+    limit = max(0, int(os.getenv("AGENTHUB_MCP_AUDIT_MAX_CHARS", "100000")))
+    return text if len(text) <= limit else text[:limit] + "...[truncated]"
+
+
+class AuditWriter:
+    def __init__(self, repo):
+        self.repo = repo
+        self.tasks = set()
+
+    def write(self, values):
+        # Map the bridge's audit fields onto Core's ``ss_mcp_audit_log`` columns.
+        code, message = values.get("error_code"), values.get("error_message")
+        if code is not None and not str(code).isdigit():
+            message, code = message or str(code), None
+        user_id = values.get("user_id")
+        row = McpAuditLog(
+            user_id=int(user_id) if str(user_id).isdigit() else None,
+            username=str(values["username"])[:128] if values.get("username") else None,
+            transport="streamable-http", mcp_session_id=values.get("session_id"),
+            client_addr=values.get("client_addr"), method=values["rpc_method"],
+            request_id=values.get("rpc_request_id"), tool_name=values.get("tool_name"),
+            request_params=values.get("request_params"), status=values["status"],
+            response_result=values.get("response_result"),
+            error_code=int(code) if code is not None else None, error_message=message,
+            duration_ms=values.get("duration_ms"))
+        with self.repo.transaction() as db:
+            db.add(row)
+
+    async def _write(self, values):
+        try:
+            await asyncio.to_thread(self.write, values)
+        except Exception:
+            logger.warning("MCP audit write failed")
+
+    def log(self, **values):
+        # Back pressure drops audit entries, not tool responses.
+        if len(self.tasks) >= 1000:
+            logger.warning("MCP audit queue full")
+            return
+        task = asyncio.create_task(self._write(values))
+        self.tasks.add(task)
+        task.add_done_callback(self.tasks.discard)
+
+    async def close(self):
+        if self.tasks:
+            await asyncio.gather(*list(self.tasks))
+
+    def purge(self):
+        days = int(os.getenv("AGENTHUB_MCP_AUDIT_RETENTION_DAYS", "0"))
+        if days > 0:
+            with self.repo.transaction() as db:
+                db.execute(delete(McpAuditLog).where(McpAuditLog.created_at < naive_now() - timedelta(days=days)))

solidx_agenthub_runtime-0.1.0/src/agenthub/bridge/auth.py

@@ -0,0 +1,98 @@
+"""Bearer authentication and workspace binding for each HTTP request."""
+
+import asyncio
+import hashlib
+import re
+from dataclasses import dataclass, field
+
+from starlette.responses import JSONResponse
+
+from agenthub.bridge.sessions import resolve
+
+
+@dataclass
+class BridgeContext:
+    agent_id: int | str
+    principal: object
+    session: object
+    explicit: bool = False
+    credential_kind: str = "jwt"
+    credential_fingerprint: str = ""
+    client_addr: str | None = None
+    process_id: str | None = None
+    client_info: dict = field(default_factory=dict)
+    audit_arguments: object = None
+    audit_response: object = None
+    human_request_id: str | None = None
+
+    def clean(self, value):
+        import json
+        text = json.dumps(value, default=str)
+        for credential in (self.principal.access_token, self.principal.api_key):
+            if credential:
+                text = text.replace(credential, "[REDACTED]")
+        return json.loads(text)
+
+
+class BridgeAuth:
+    def __init__(self, app, manager, audit):
+        self.app, self.manager, self.audit = app, manager, audit
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+        match = re.fullmatch(r"/mcp/agents/([^/]+)(?:/sessions/([^/]+))?/?", scope["path"])
+        if not match:
+            await JSONResponse({"error": "MCP endpoint not found"}, 404)(scope, receive, send)
+            return
+        agent_id, sid = match.groups()
+        try:
+            agent_id = int(agent_id)
+        except ValueError:
+            await JSONResponse({"error": "MCP endpoint not found"}, 404)(scope, receive, send)
+            return
+        headers = dict(scope.get("headers", ()))
+        auth = headers.get(b"authorization", b"").decode("latin-1")
+        api_key = headers.get(b"solidx-api-key", b"").decode("latin-1") or None
+        token = auth[7:].strip() if auth.startswith("Bearer ") else None
+        principal = None
+        kind = "api_key" if api_key else "jwt"
+        status, message = 401, "Invalid credentials"
+        try:
+            if token and not api_key:
+                try:
+                    principal = await asyncio.to_thread(self.manager.identity.validate, token=token)
+                except Exception:
+                    # Bearer API keys are a compatibility extension, not OAuth.
+                    principal = await asyncio.to_thread(self.manager.identity.validate, api_key=token)
+                    kind = "api_key"
+            elif api_key and not token:
+                principal = await asyncio.to_thread(self.manager.identity.validate, api_key=api_key)
+            else:
+                raise PermissionError("Missing or ambiguous credential")
+        except Exception:
+            pass
+        if principal:
+            try:
+                session = await asyncio.to_thread(resolve, self.manager.repo, agent_id, principal, sid)
+            except PermissionError:
+                status, message = 403, "Agent or session access denied"
+            except LookupError:
+                status, message = 404, "Agent or session unavailable"
+            else:
+                scoped = BridgeContext(
+                    agent_id, principal, session, bool(sid), kind,
+                    hashlib.sha256((api_key or token).encode()).hexdigest()[:16],
+                    (scope.get("client") or (None,))[0],
+                )
+                inner = dict(scope)
+                inner["bridge_context"] = scoped
+                inner["path"], inner["raw_path"], inner["root_path"] = "/", b"/", ""
+                await self.app(inner, receive, send)
+                return
+        self.audit.log(agent_id=agent_id, user_id=principal.id if principal else None,
+                       rpc_method="auth.denied", status="denied", error_code=str(status),
+                       error_message=message, client_addr=(scope.get("client") or (None,))[0])
+        await JSONResponse({"error": message}, status, headers={"WWW-Authenticate": "Bearer"} if status == 401
+                           else {})(scope, receive, send)

solidx_agenthub_runtime-0.1.0/src/agenthub/bridge/local.py

@@ -0,0 +1,123 @@
+"""Disk-mode MCP backend: one local user, in-process tools, prompt-only approvals."""
+
+import asyncio
+import json
+import os
+from datetime import datetime, timedelta, timezone
+from threading import RLock
+from types import SimpleNamespace
+from uuid import uuid4
+
+from agenthub.bridge.auth import BridgeContext
+from agenthub.bridge.tool_session import PROMPT_APPROVALS, ToolSession, catalog
+from agenthub.tools.executor import ParkSession
+from agenthub.tools.loader import ToolRegistry
+
+LOCAL_PRINCIPAL = SimpleNamespace(id="local", username="local", role_ids=(), access_token=None, api_key=None)
+
+
+class LocalAudit:
+    def __init__(self, store=None):
+        self.store = store
+        if store:
+            with store.lock, store.db:
+                store.db.execute("CREATE TABLE IF NOT EXISTS mcp_calls "
+                                 "(id INTEGER PRIMARY KEY, session_id TEXT, data TEXT, created_at TEXT)")
+
+    def log(self, **values):
+        if not self.store:
+            return
+        with self.store.lock, self.store.db:
+            self.store.db.execute("INSERT INTO mcp_calls (session_id, data, created_at) VALUES (?, ?, ?)",
+                                  (values.get("session_id"), json.dumps(values, default=str),
+                                   datetime.now(timezone.utc).isoformat()))
+
+    async def close(self):
+        return None
+
+
+class LocalBridge:
+    # No AgentHub UI exists in disk mode, so approvals must arrive through MCP elicitation.
+    out_of_band_approvals = False
+
+    def __init__(self, spec, store=None):
+        self.spec = spec
+        self.registry = ToolRegistry(spec.tools)
+        self.audit = LocalAudit(store)
+        self.lock = RLock()
+        self.pending = {}
+        self.session = self._new_session()
+
+    def _new_session(self):
+        return ToolSession(self.spec, self.registry, str(uuid4()))
+
+    def _principal(self):
+        return {"id": LOCAL_PRINCIPAL.id, "username": LOCAL_PRINCIPAL.username, "role_ids": ()}
+
+    def scope(self, ctx):
+        # The audit middleware and handlers must share one mutable scope per request.
+        scope = getattr(ctx, "_agenthub_scope", None)
+        if scope is None:
+            scope = BridgeContext(self.spec.agent_id, LOCAL_PRINCIPAL, SimpleNamespace(id=self.session.id),
+                                  credential_kind="local")
+            ctx._agenthub_scope = scope
+        return scope
+
+    async def catalog(self, scope):
+        return self.session.redact(catalog(self.spec, self.registry, PROMPT_APPROVALS), {})
+
+    async def call(self, scope, name, arguments):
+        session = self.session
+        action = {"tool_name": name, "arguments": arguments, "tool_call_id": str(uuid4())}
+        redacted = session.redact(arguments, self._principal())
+        scope.audit_arguments = redacted
+        try:
+            output = await asyncio.to_thread(session.call, action, self._principal())
+        except ParkSession as pause:
+            rid = str(uuid4())
+            ttl = int(os.getenv("AGENTHUB_MCP_APPROVAL_TTL", "900"))
+            with self.lock:
+                self.pending = {k: v for k, v in self.pending.items()
+                                if v["expires_at"] > datetime.now(timezone.utc)}
+                self.pending[rid] = {"session": session, "action": action, "status": "pending",
+                                     "expires_at": datetime.now(timezone.utc) + timedelta(seconds=ttl)}
+            scope.human_request_id = rid
+            return {"status": "approval_required", "request_id": rid, "question": pause.question}
+        return {"status": "error" if output["returncode"] else "ok", "output": output["output"]}
+
+    async def answer(self, scope, rid, approve):
+        with self.lock:
+            request = self.pending.get(rid)
+            if not request or request["session"] is not self.session or request["status"] != "pending":
+                raise PermissionError("Invalid approval request")
+            request["status"] = "approved" if approve else "rejected"
+
+    async def resume(self, scope, rid):
+        scope.human_request_id = rid
+        with self.lock:
+            request = self.pending.get(rid)
+            if not request or request["session"] is not self.session:
+                return {"status": "error", "output": '{"error":"Request not found"}'}
+            if "result" in request:
+                return request["result"]
+            if request["status"] == "pending" and datetime.now(timezone.utc) >= request["expires_at"]:
+                request["status"] = "expired"
+            if request["status"] != "approved":
+                return {"status": request["status"]}
+            request["status"] = "executing"
+        result = await asyncio.to_thread(request["session"].call, request["action"], self._principal(),
+                                         approved=True)
+        output = {"status": "error" if result["returncode"] else "ok", "output": result["output"]}
+        with self.lock:
+            request["status"], request["result"] = "executed", output
+        return output
+
+    async def rotate(self, scope):
+        with self.lock:
+            self.session = self._new_session()
+            self.pending.clear()
+        scope.session = SimpleNamespace(id=self.session.id)
+        return {"status": "ok", "output": json.dumps({"session_id": self.session.id})}
+
+    async def close(self):
+        return None