feat: safety governance layer — kill switch & admin controls

alembic/versions/2026_04_09_0001-add_is_admin_to_users.py

@@ -0,0 +1,26 @@
+"""add is_admin column to users table
+
+Revision ID: add_is_admin_to_users
+Revises: add_communication_networks
+Create Date: 2026-04-09 00:01:00.000000
+
+"""
+from alembic import op
+import sqlalchemy as sa
+
+# revision identifiers, used by Alembic.
+revision = "add_is_admin_to_users"
+down_revision = "add_communication_networks"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.add_column(
+        "users",
+        sa.Column("is_admin", sa.Boolean(), nullable=False, server_default="false"),
+    )
+
+
+def downgrade() -> None:
+    op.drop_column("users", "is_admin")

alembic/versions/2026_04_09_0002-add_halt_codes_table.py

@@ -0,0 +1,36 @@
+"""add halt_codes table for distributed kill switch
+
+Revision ID: add_halt_codes
+Revises: add_is_admin_to_users
+Create Date: 2026-04-09 00:02:00.000000
+
+"""
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects.postgresql import UUID
+
+# revision identifiers, used by Alembic.
+revision = "add_halt_codes"
+down_revision = "add_is_admin_to_users"
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "halt_codes",
+        sa.Column("id", UUID(as_uuid=True), primary_key=True),
+        sa.Column("code_hash", sa.String(), nullable=False),
+        sa.Column("label", sa.String(), nullable=False),
+        sa.Column("trustee_name", sa.String(), nullable=False),
+        sa.Column("trustee_email", sa.String(), nullable=True),
+        sa.Column("is_master", sa.Boolean(), nullable=False, server_default="false"),
+        sa.Column("is_active", sa.Boolean(), nullable=False, server_default="true"),
+        sa.Column("created_by", UUID(as_uuid=True), sa.ForeignKey("users.id"), nullable=False),
+        sa.Column("created_at", sa.DateTime(timezone=True), server_default=sa.func.now()),
+        sa.Column("updated_at", sa.DateTime(timezone=True), server_default=sa.func.now()),
+    )
+
+
+def downgrade() -> None:
+    op.drop_table("halt_codes")

src/core/admin_auth.py

@@ -0,0 +1,20 @@
+"""Admin authentication dependency."""
+
+from fastapi import Depends
+
+from src.core.auth import get_current_user
+from src.exceptions import ForbiddenException
+from src.models.auth import User
+
+
+async def get_admin_user(
+    current_user: User = Depends(get_current_user),
+) -> User:
+    """Require the current user to be an admin.
+
+    Wraps get_current_user and raises 403 if the user does not have
+    the is_admin flag set.
+    """
+    if not getattr(current_user, "is_admin", False):
+        raise ForbiddenException("Admin access required")
+    return current_user

src/core/settings.py

@@ -103,6 +103,10 @@ class Settings(BaseSettings):
     NETWORK_CALLBACK_TIMEOUT_SECONDS: int = 30
     NETWORK_MESSAGE_DELIVERY_MAX_RETRIES: int = 3
 
+    # ── Safety & Governance ─────────────────────────────────────────────
+    SAFETY_CHECK_ENABLED: bool = True
+    AGENT_STATUS_CACHE_TTL: int = 300  # seconds to cache agent active status in Redis
+
     # ── Economy settings (from agent-economy) ──────────────────────────
     ECONOMY_WELCOME_BONUS_CREDITS: int = 500
     ECONOMY_CREDIT_PACKAGES: list[dict] = [

src/exceptions.py

@@ -12,6 +12,8 @@
     "ValidationException",
     "DatabaseException",
     "RateLimitException",
+    "PlatformHaltedException",
+    "AgentDisabledException",
 ]
 
 
@@ -91,3 +93,18 @@ class RateLimitException(BaseCustomException):
 
     def __init__(self, detail: str = "Rate limit exceeded. Please try again later"):
         super().__init__(status_code=status.HTTP_429_TOO_MANY_REQUESTS, detail=detail)
+
+
+# Safety & Governance Exceptions
+class PlatformHaltedException(BaseCustomException):
+    """Exception raised when the platform is in emergency halt mode"""
+
+    def __init__(self, detail: str = "Platform is in emergency halt mode. All agent operations are suspended."):
+        super().__init__(status_code=status.HTTP_503_SERVICE_UNAVAILABLE, detail=detail)
+
+
+class AgentDisabledException(BaseCustomException):
+    """Exception raised when a disabled agent is invoked"""
+
+    def __init__(self, detail: str = "Agent has been disabled by an administrator"):
+        super().__init__(status_code=status.HTTP_403_FORBIDDEN, detail=detail)

src/main.py

@@ -30,6 +30,8 @@
 from src.routes.message import router as message_router
 from src.routes.registry import router as registry_router
 from src.routes.task import router as task_router
+from src.routes.admin import router as admin_router
+from src.routes.safety import router as safety_router
 from src.mcp_app import create_mcp_app
 
 # Workflow routers (from agent-os)
@@ -232,6 +234,10 @@ async def handle_workflow_exception(_request: Request, exc: WorkflowAppException
 app.include_router(invocation_log_router)
 app.include_router(task_router)
 
+# ── Admin / Safety routers ───────────────────────────────────────────
+app.include_router(admin_router, tags=["Admin"])
+app.include_router(safety_router, tags=["Safety"])
+
 # ── Workflow routers (from agent-os) ─────────────────────────────────
 app.include_router(workflow_router, prefix="/workflows", tags=["Workflows"])
 app.include_router(execution_router, tags=["Executions"])

src/models/__init__.py

@@ -12,6 +12,7 @@
 from src.models.message import Message
 from src.models.registry import Agent, AgentCredential, AgentRating
 from src.models.task import Task
+from src.models.halt_code import HaltCode
 
 # Workflow models (from agent-os)
 from src.workflow.models.entities import (  # noqa: F401
@@ -47,6 +48,7 @@
     "AgentCredential",
     "InvocationLog",
     "Task",
+    "HaltCode",
     # Workflow
     "WorkflowDefinition",
     "WorkflowExecution",

src/models/auth.py

@@ -22,6 +22,7 @@ class User(BaseModel):
     last_name: Column[str] = Column(String, nullable=True)
     phone_number: Column[str] = Column(String, nullable=True, unique=True)
     is_active: Column[bool] = Column(Boolean, default=True, nullable=False)
+    is_admin: Column[bool] = Column(Boolean, default=False, nullable=False)
 
     # Relationships
     api_keys = relationship("ApiKey", back_populates="user", cascade="all, delete-orphan")

src/models/halt_code.py

@@ -0,0 +1,25 @@
+"""Halt code model — distributed kill switch codes for trustees."""
+
+from typing import Optional
+from uuid import UUID
+
+from sqlalchemy import Boolean, Column, ForeignKey, String
+from sqlalchemy.dialects.postgresql import UUID as PostgresUUID
+
+from .base import BaseModel
+
+
+class HaltCode(BaseModel):
+    """A halt code held by a trustee who can stop the platform."""
+
+    __tablename__: str = "halt_codes"
+
+    code_hash: Column[str] = Column(String, nullable=False)
+    label: Column[str] = Column(String, nullable=False)
+    trustee_name: Column[str] = Column(String, nullable=False)
+    trustee_email: Column[Optional[str]] = Column(String, nullable=True)
+    is_master: Column[bool] = Column(Boolean, default=False, nullable=False)
+    is_active: Column[bool] = Column(Boolean, default=True, nullable=False)
+    created_by: Column[UUID] = Column(
+        PostgresUUID, ForeignKey("users.id"), nullable=False
+    )

src/network/a2a/routes.py

@@ -79,6 +79,10 @@ async def a2a_task_send(
     from src.network.utils.context_manager import NetworkContextManager
     from src.database import get_redis
 
+    # Safety check: reject if platform is in emergency halt
+    from src.services.safety import check_platform_halt
+    await check_platform_halt()
+
     params = data.params
     task_data = params.get("task", {})
     network_id = params.get("network_id")

src/network/services/channels.py

@@ -258,6 +258,10 @@ async def handle_callback(
         This is the key to bidirectionality: external agents POST to their
         reply_url and this method records the message in the network.
         """
+        # Safety check: reject if platform is in emergency halt
+        from src.services.safety import check_platform_halt
+        await check_platform_halt()
+
         sender = await self.repo.get_participant(participant_id)
         if not sender or sender.network_id != network_id:
             raise NotFoundException("Participant")
@@ -322,6 +326,10 @@ async def _validate_communication(
         sender_id: UUID,
         recipient_id: UUID,
     ) -> tuple[NetworkParticipant, NetworkParticipant, CommunicationNetwork]:
+        # Safety check: reject if platform is in emergency halt
+        from src.services.safety import check_agent_active, check_platform_halt
+        await check_platform_halt()
+
         network = await self.repo.get_network(network_id)
         if not network:
             raise NotFoundException("Network")
@@ -340,6 +348,12 @@ async def _validate_communication(
         if recipient.status != ParticipantStatus.active:
             raise BadRequestException("Recipient is not active")
 
+        # Safety check: verify linked agents are still active
+        if sender.agent_id:
+            await check_agent_active(sender.agent_id)
+        if recipient.agent_id:
+            await check_agent_active(recipient.agent_id)
+
         return sender, recipient, network
 
     async def _record_message(