aegis-idempotency 0.1.0__tar.gz

aegis_idempotency-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cristian Amigo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aegis_idempotency-0.1.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: aegis-idempotency
+Version: 0.1.0
+Summary: HTTP client for the AEGIS HITL Reliability Layer — exactly-once human-in-the-loop approvals for AI agents
+Author-email: Cristian Amigo <cstamigo@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/cstamigo/aegis-hitl
+Project-URL: Bug Tracker, https://github.com/cstamigo/aegis-hitl/issues
+Keywords: hitl,idempotency,reliability,agents,ai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Dynamic: license-file
+
+# aegis-idempotency
+
+> **Note:** The final distribution name on PyPI will be confirmed before publishing.
+> The package import name is `aegis_hitl` regardless of the distribution name.
+
+HTTP client for the [AEGIS HITL Reliability Layer](https://github.com/cstamigo/aegis-idempotency) —
+exactly-once human-in-the-loop approvals for AI agents.
+
+## Installation
+
+```bash
+pip install aegis-idempotency
+```
+
+## Quick Start
+
+```python
+import asyncio
+from aegis_hitl import AegisClient
+
+async def main():
+    async with AegisClient(
+        base_url="http://localhost:8000",
+        tenant_id="my-tenant",
+        thread_id="my-thread",
+    ) as client:
+        # Approve a pending agent action
+        response = await client.approve("idempotency-key-001")
+        print(response.status_code)  # 202
+
+asyncio.run(main())
+```
+
+## API Reference
+
+### `AegisClient(base_url, *, tenant_id, thread_id, timeout, client)`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `base_url` | `str` | `"http://localhost:8000"` | AEGIS server URL |
+| `tenant_id` | `str \| None` | `None` | Default tenant; override per call |
+| `thread_id` | `str \| None` | `None` | Default thread; override per call |
+| `timeout` | `float` | `10.0` | Request timeout in seconds |
+| `client` | `httpx.AsyncClient \| None` | `None` | Inject an existing httpx client |
+
+Must be used as an async context manager (`async with`).
+
+### Methods
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `approve(idempotency_key, *, tenant_id, thread_id, payload)` | `POST /hitl/approve` | Approve a pending action |
+| `reject(idempotency_key, *, tenant_id, thread_id, payload)` | `POST /hitl/reject` | Reject a pending action |
+| `execute(action, idempotency_key, ...)` | `POST /hitl/{action}` | Generic approve/reject dispatcher |
+| `get_status(request_id)` | `GET /hitl/status/{id}` | Query action status |
+
+### Response Status Codes
+
+| Code | Meaning |
+|------|---------|
+| `202` | Action processed successfully |
+| `409` | Duplicate request (idempotency key already used) |
+| `500` | Internal server error |
+
+## Publishing
+
+To publish to PyPI (when ready):
+
+```bash
+python -m build
+twine check dist/*
+twine upload dist/*  # requires PyPI account and token
+```
+
+> Warning: Confirm the distribution name availability on PyPI before uploading.

aegis_idempotency-0.1.0/README_SDK.md

@@ -0,0 +1,75 @@
+# aegis-idempotency
+
+> **Note:** The final distribution name on PyPI will be confirmed before publishing.
+> The package import name is `aegis_hitl` regardless of the distribution name.
+
+HTTP client for the [AEGIS HITL Reliability Layer](https://github.com/cstamigo/aegis-idempotency) —
+exactly-once human-in-the-loop approvals for AI agents.
+
+## Installation
+
+```bash
+pip install aegis-idempotency
+```
+
+## Quick Start
+
+```python
+import asyncio
+from aegis_hitl import AegisClient
+
+async def main():
+    async with AegisClient(
+        base_url="http://localhost:8000",
+        tenant_id="my-tenant",
+        thread_id="my-thread",
+    ) as client:
+        # Approve a pending agent action
+        response = await client.approve("idempotency-key-001")
+        print(response.status_code)  # 202
+
+asyncio.run(main())
+```
+
+## API Reference
+
+### `AegisClient(base_url, *, tenant_id, thread_id, timeout, client)`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `base_url` | `str` | `"http://localhost:8000"` | AEGIS server URL |
+| `tenant_id` | `str \| None` | `None` | Default tenant; override per call |
+| `thread_id` | `str \| None` | `None` | Default thread; override per call |
+| `timeout` | `float` | `10.0` | Request timeout in seconds |
+| `client` | `httpx.AsyncClient \| None` | `None` | Inject an existing httpx client |
+
+Must be used as an async context manager (`async with`).
+
+### Methods
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `approve(idempotency_key, *, tenant_id, thread_id, payload)` | `POST /hitl/approve` | Approve a pending action |
+| `reject(idempotency_key, *, tenant_id, thread_id, payload)` | `POST /hitl/reject` | Reject a pending action |
+| `execute(action, idempotency_key, ...)` | `POST /hitl/{action}` | Generic approve/reject dispatcher |
+| `get_status(request_id)` | `GET /hitl/status/{id}` | Query action status |
+
+### Response Status Codes
+
+| Code | Meaning |
+|------|---------|
+| `202` | Action processed successfully |
+| `409` | Duplicate request (idempotency key already used) |
+| `500` | Internal server error |
+
+## Publishing
+
+To publish to PyPI (when ready):
+
+```bash
+python -m build
+twine check dist/*
+twine upload dist/*  # requires PyPI account and token
+```
+
+> Warning: Confirm the distribution name availability on PyPI before uploading.

aegis_idempotency-0.1.0/aegis_hitl/__init__.py

@@ -0,0 +1,4 @@
+from aegis_hitl.client import AegisClient
+
+__version__ = "0.1.0"
+__all__ = ["AegisClient"]

aegis_idempotency-0.1.0/aegis_hitl/client.py

@@ -0,0 +1,143 @@
+import asyncio
+import uuid
+import httpx
+from typing import Any
+
+
+class AegisClient:
+    """HTTP client for the AEGIS HITL Reliability Layer.
+
+    Usage::
+
+        async with AegisClient(
+            base_url="http://localhost:8000",
+            tenant_id="t1",
+            thread_id="thr1",
+        ) as client:
+            response = await client.approve("idempotency-key-123")
+            assert response.status_code == 202
+
+    tenant_id and thread_id can be overridden per call.
+    """
+
+    def __init__(
+        self,
+        base_url: str = "http://localhost:8000",
+        *,
+        tenant_id: str | None = None,
+        thread_id: str | None = None,
+        timeout: float = 10.0,
+        max_retries: int = 3,
+        api_prefix: str = "/api/v1",
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.tenant_id = tenant_id
+        self.thread_id = thread_id
+        self.timeout = timeout
+        self.max_retries = max_retries
+        self.api_prefix = api_prefix.rstrip("/")
+        self._external_client = client
+        self._client: httpx.AsyncClient | None = None
+
+    async def __aenter__(self) -> "AegisClient":
+        self._client = self._external_client or httpx.AsyncClient(
+            base_url=self.base_url, timeout=self.timeout
+        )
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc: Any, tb: Any) -> bool:
+        if self._client and not self._external_client:
+            await self._client.aclose()
+        self._client = None
+        return False
+
+    def _resolve(self, tenant_id: str | None, thread_id: str | None) -> tuple[str, str]:
+        t = tenant_id or self.tenant_id
+        th = thread_id or self.thread_id
+        if not t:
+            raise ValueError("tenant_id is required (set on constructor or per call)")
+        if not th:
+            raise ValueError("thread_id is required (set on constructor or per call)")
+        return t, th
+
+    def _headers(
+        self,
+        tenant_id: str,
+        thread_id: str,
+        idempotency_key: str,
+    ) -> dict[str, str]:
+        return {
+            "Tenant-Id": tenant_id,
+            "Thread-Id": thread_id,
+            "Idempotency-Key": idempotency_key,
+            "X-Request-Id": str(uuid.uuid4()),
+        }
+
+    async def _post(
+        self,
+        path: str,
+        idempotency_key: str,
+        tenant_id: str | None,
+        thread_id: str | None,
+        payload: dict[str, Any] | None,
+    ) -> httpx.Response:
+        if not self._client:
+            raise RuntimeError("AegisClient must be used as an async context manager.")
+        t, th = self._resolve(tenant_id, thread_id)
+        headers = self._headers(t, th, idempotency_key)
+        delays = [0.5, 1.0, 2.0]
+        last_response: httpx.Response | None = None
+        for attempt in range(self.max_retries + 1):
+            full_path = f"{self.api_prefix}{path}"
+            response = await self._client.post(full_path, headers=headers, json=payload or {})
+            if response.status_code < 500:
+                return response
+            last_response = response
+            if attempt < self.max_retries:
+                await asyncio.sleep(delays[min(attempt, len(delays) - 1)])
+        return last_response  # type: ignore[return-value]
+
+    async def approve(
+        self,
+        idempotency_key: str,
+        *,
+        tenant_id: str | None = None,
+        thread_id: str | None = None,
+        payload: dict[str, Any] | None = None,
+    ) -> httpx.Response:
+        """POST /hitl/approve. Returns raw httpx.Response (202 ok, 409 duplicate)."""
+        return await self._post("/hitl/approve", idempotency_key, tenant_id, thread_id, payload)
+
+    async def reject(
+        self,
+        idempotency_key: str,
+        *,
+        tenant_id: str | None = None,
+        thread_id: str | None = None,
+        payload: dict[str, Any] | None = None,
+    ) -> httpx.Response:
+        """POST /hitl/reject. Returns raw httpx.Response (202 ok, 409 duplicate)."""
+        return await self._post("/hitl/reject", idempotency_key, tenant_id, thread_id, payload)
+
+    async def execute(
+        self,
+        action: str,
+        idempotency_key: str,
+        *,
+        tenant_id: str | None = None,
+        thread_id: str | None = None,
+        payload: dict[str, Any] | None = None,
+    ) -> httpx.Response:
+        """Dispatch to approve or reject based on action string."""
+        if action not in {"approve", "reject"}:
+            raise ValueError(f"action must be 'approve' or 'reject', got {action!r}")
+        return await self._post(
+            f"/hitl/{action}", idempotency_key, tenant_id, thread_id, payload
+        )
+
+    async def get_status(self, request_id: str) -> httpx.Response:
+        """GET /hitl/status/{request_id}."""
+        if not self._client:
+            raise RuntimeError("AegisClient must be used as an async context manager.")
+        return await self._client.get(f"{self.api_prefix}/hitl/status/{request_id}")

aegis_idempotency-0.1.0/aegis_idempotency.egg-info/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: aegis-idempotency
+Version: 0.1.0
+Summary: HTTP client for the AEGIS HITL Reliability Layer — exactly-once human-in-the-loop approvals for AI agents
+Author-email: Cristian Amigo <cstamigo@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/cstamigo/aegis-hitl
+Project-URL: Bug Tracker, https://github.com/cstamigo/aegis-hitl/issues
+Keywords: hitl,idempotency,reliability,agents,ai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Dynamic: license-file
+
+# aegis-idempotency
+
+> **Note:** The final distribution name on PyPI will be confirmed before publishing.
+> The package import name is `aegis_hitl` regardless of the distribution name.
+
+HTTP client for the [AEGIS HITL Reliability Layer](https://github.com/cstamigo/aegis-idempotency) —
+exactly-once human-in-the-loop approvals for AI agents.
+
+## Installation
+
+```bash
+pip install aegis-idempotency
+```
+
+## Quick Start
+
+```python
+import asyncio
+from aegis_hitl import AegisClient
+
+async def main():
+    async with AegisClient(
+        base_url="http://localhost:8000",
+        tenant_id="my-tenant",
+        thread_id="my-thread",
+    ) as client:
+        # Approve a pending agent action
+        response = await client.approve("idempotency-key-001")
+        print(response.status_code)  # 202
+
+asyncio.run(main())
+```
+
+## API Reference
+
+### `AegisClient(base_url, *, tenant_id, thread_id, timeout, client)`
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `base_url` | `str` | `"http://localhost:8000"` | AEGIS server URL |
+| `tenant_id` | `str \| None` | `None` | Default tenant; override per call |
+| `thread_id` | `str \| None` | `None` | Default thread; override per call |
+| `timeout` | `float` | `10.0` | Request timeout in seconds |
+| `client` | `httpx.AsyncClient \| None` | `None` | Inject an existing httpx client |
+
+Must be used as an async context manager (`async with`).
+
+### Methods
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `approve(idempotency_key, *, tenant_id, thread_id, payload)` | `POST /hitl/approve` | Approve a pending action |
+| `reject(idempotency_key, *, tenant_id, thread_id, payload)` | `POST /hitl/reject` | Reject a pending action |
+| `execute(action, idempotency_key, ...)` | `POST /hitl/{action}` | Generic approve/reject dispatcher |
+| `get_status(request_id)` | `GET /hitl/status/{id}` | Query action status |
+
+### Response Status Codes
+
+| Code | Meaning |
+|------|---------|
+| `202` | Action processed successfully |
+| `409` | Duplicate request (idempotency key already used) |
+| `500` | Internal server error |
+
+## Publishing
+
+To publish to PyPI (when ready):
+
+```bash
+python -m build
+twine check dist/*
+twine upload dist/*  # requires PyPI account and token
+```
+
+> Warning: Confirm the distribution name availability on PyPI before uploading.

aegis_idempotency-0.1.0/aegis_idempotency.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README_SDK.md
+pyproject.toml
+aegis_hitl/__init__.py
+aegis_hitl/client.py
+aegis_idempotency.egg-info/PKG-INFO
+aegis_idempotency.egg-info/SOURCES.txt
+aegis_idempotency.egg-info/dependency_links.txt
+aegis_idempotency.egg-info/requires.txt
+aegis_idempotency.egg-info/top_level.txt
+tests/test_billing_exact_once.py
+tests/test_crash_recovery.py
+tests/test_hitl_concurrency.py
+tests/test_sdk_client.py

aegis_idempotency-0.1.0/aegis_idempotency.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

aegis_idempotency-0.1.0/aegis_idempotency.egg-info/requires.txt

@@ -0,0 +1 @@
+httpx>=0.27

aegis_idempotency-0.1.0/aegis_idempotency.egg-info/top_level.txt

@@ -0,0 +1 @@
+aegis_hitl

aegis_idempotency-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "aegis-idempotency"
+version = "0.1.0"
+description = "HTTP client for the AEGIS HITL Reliability Layer — exactly-once human-in-the-loop approvals for AI agents"
+readme = "README_SDK.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "Cristian Amigo", email = "cstamigo@gmail.com" }]
+keywords = ["hitl", "idempotency", "reliability", "agents", "ai"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Internet :: WWW/HTTP",
+]
+dependencies = ["httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://github.com/cstamigo/aegis-hitl"
+"Bug Tracker" = "https://github.com/cstamigo/aegis-hitl/issues"
+
+[tool.setuptools.packages.find]
+include = ["aegis_hitl*"]
+
+[tool.setuptools.package-data]
+"aegis_hitl" = ["py.typed"]

aegis_idempotency-0.1.0/setup.cfg

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

aegis_idempotency-0.1.0/tests/test_billing_exact_once.py

@@ -0,0 +1,9 @@
+import pytest
+
+def test_app_import():
+    """Ensure the FastAPI application can be imported without errors.
+    This is a minimal sanity check required for the test suite to discover
+    at least one test file.
+    """
+    from api.main import app
+    assert app is not None

aegis_idempotency-0.1.0/tests/test_crash_recovery.py

@@ -0,0 +1,148 @@
+"""Tests de crash recovery para AEGIS HITL.
+
+Verifica que el ExecutionJanitor limpia correctamente los registros
+hitl_idempotency con status=PENDING que quedaron huérfanos tras un crash.
+Requiere Docker corriendo (Testcontainers via conftest.py).
+"""
+
+import pytest
+from datetime import datetime, timedelta, timezone
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession
+
+import httpx
+
+from core.janitor import ExecutionJanitor
+
+# UUIDs deterministas alineados con conftest.py (seed_executions)
+TENANT_UUIDS = {f"t{i}": f"00000000-0000-0000-0000-{i:012d}" for i in range(1, 21)}
+THREAD_UUIDS = {f"thr{i}": f"00000000-0000-0000-0001-{i:012d}" for i in range(1, 21)}
+
+# Usamos t5/thr5 para evitar colisiones con los tests de concurrencia (t1-t4)
+_TENANT = TENANT_UUIDS["t5"]
+_THREAD = THREAD_UUIDS["thr5"]
+
+
+# ---------------------------------------------------------------------------
+# TEST 1 — Janitor limpia PENDING huérfano
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_orphaned_pending_cleaned_by_janitor(async_session: AsyncSession, async_engine):
+    """Un PENDING huérfano (10 min) debe quedar FAILED tras llamar _cleanup_orphaned_pending."""
+    from sqlalchemy.ext.asyncio import AsyncSession as _AS, async_sessionmaker
+
+    key = "orphan-key-janitor-test"
+    cutoff = datetime.now(timezone.utc) - timedelta(minutes=10)
+
+    # Insertar row PENDING con created_at en el pasado
+    factory = async_sessionmaker(async_engine, class_=_AS, expire_on_commit=False)
+    async with factory() as s:
+        await s.execute(
+            text(
+                """
+                INSERT INTO hitl_idempotency
+                    (id, tenant_id, thread_id, idempotency_key, status, created_at)
+                VALUES
+                    (gen_random_uuid(), :tid, :thid, :key, 'PENDING', :ts)
+                ON CONFLICT ON CONSTRAINT uq_hitl_idempotency DO UPDATE
+                    SET status = 'PENDING', created_at = EXCLUDED.created_at
+                """
+            ),
+            {"tid": _TENANT, "thid": _THREAD, "key": key, "ts": cutoff},
+        )
+        await s.commit()
+
+    # Instanciar janitor con TTL de 5 min y ejecutar solo el cleanup de PENDINGs
+    import core.database as db_module
+    from sqlalchemy.ext.asyncio import async_sessionmaker as _asm
+
+    original = db_module.AsyncSessionLocal
+    db_module.AsyncSessionLocal = _asm(async_engine, class_=_AS, expire_on_commit=False)
+    try:
+        janitor = ExecutionJanitor(pending_ttl=timedelta(minutes=5))
+        count = await janitor._cleanup_orphaned_pending()
+    finally:
+        db_module.AsyncSessionLocal = original
+
+    assert count >= 1, f"Esperaba al menos 1 row limpiado, got {count}"
+
+    # Verificar en DB que el row quedó FAILED
+    res = await async_session.execute(
+        text(
+            "SELECT status FROM hitl_idempotency "
+            "WHERE tenant_id=:tid AND thread_id=:thid AND idempotency_key=:key"
+        ),
+        {"tid": _TENANT, "thid": _THREAD, "key": key},
+    )
+    row = res.fetchone()
+    assert row is not None, "El row debe existir en DB"
+    assert row[0] == "FAILED", f"Status esperado FAILED, got {row[0]}"
+
+
+# ---------------------------------------------------------------------------
+# TEST 2 — Después de limpiar el huérfano, la misma key puede usarse de nuevo
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_new_request_succeeds_after_orphan_cleanup(
+    async_engine,
+    client: httpx.AsyncClient,
+):
+    """Después de que el janitor limpia un PENDING huérfano,
+    una nueva request con la misma key debe devolver 202 (no 409).
+    """
+    from sqlalchemy.ext.asyncio import AsyncSession as _AS, async_sessionmaker
+
+    # Usar t6/thr6 para que seed_executions tenga el EvaluationExecution necesario
+    tenant = TENANT_UUIDS["t6"]
+    thread = THREAD_UUIDS["thr6"]
+    key = "orphan-key-http-test"
+    cutoff = datetime.now(timezone.utc) - timedelta(minutes=10)
+
+    # 1. Insertar PENDING huérfano
+    factory = async_sessionmaker(async_engine, class_=_AS, expire_on_commit=False)
+    async with factory() as s:
+        await s.execute(
+            text(
+                """
+                INSERT INTO hitl_idempotency
+                    (id, tenant_id, thread_id, idempotency_key, status, created_at)
+                VALUES
+                    (gen_random_uuid(), :tid, :thid, :key, 'PENDING', :ts)
+                ON CONFLICT ON CONSTRAINT uq_hitl_idempotency DO UPDATE
+                    SET status = 'PENDING', created_at = EXCLUDED.created_at
+                """
+            ),
+            {"tid": tenant, "thid": thread, "key": key, "ts": cutoff},
+        )
+        await s.commit()
+
+    # Verificar que sin cleanup devolvería 409 (PENDING activo)
+    # (omitido para evitar side effects en el lifecycle; confiamos en el middleware)
+
+    # 2. Limpiar con janitor
+    import core.database as db_module
+
+    original = db_module.AsyncSessionLocal
+    db_module.AsyncSessionLocal = async_sessionmaker(async_engine, class_=_AS, expire_on_commit=False)
+    try:
+        janitor = ExecutionJanitor(pending_ttl=timedelta(minutes=5))
+        count = await janitor._cleanup_orphaned_pending()
+    finally:
+        db_module.AsyncSessionLocal = original
+
+    assert count >= 1, f"Janitor debía limpiar al menos 1 row, got {count}"
+
+    # 3. Request HTTP con la misma idempotency_key — debe ser 202 ahora
+    headers = {
+        "tenant-id": tenant,
+        "Thread-Id": thread,
+        "Idempotency-Key": key,
+    }
+    body = {"tenant_id": tenant, "thread_id": thread}
+
+    response = await client.post("/api/v1/hitl/approve", headers=headers, json=body)
+    assert response.status_code == 202, (
+        f"Esperaba 202 tras cleanup del huérfano, got {response.status_code}: {response.text}"
+    )

aegis_idempotency-0.1.0/tests/test_hitl_concurrency.py

@@ -0,0 +1,324 @@
+# tests/test_hitl_concurrency.py
+"""Production‑grade concurrency and idempotency validation for the HITL system.
+This suite runs against a real PostgreSQL container (via testcontainers),
+applies migrations, and exercises the FastAPI app with highly concurrent
+requests.
+"""
+
+import asyncio
+import random
+from typing import List
+from uuid import UUID
+
+import httpx
+import pytest
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from tests.utils.invariant_checker import check_global_invariants
+
+# ---------------------------------------------------------------------------
+# Fixed UUIDs for deterministic test tenants/threads
+# ---------------------------------------------------------------------------
+TENANT_UUIDS = {f"t{i}": f"00000000-0000-0000-0000-{i:012d}" for i in range(1, 21)}
+THREAD_UUIDS = {f"thr{i}": f"00000000-0000-0000-0001-{i:012d}" for i in range(1, 21)}
+
+# ---------------------------------------------------------------------------
+# Helper utilities
+# ---------------------------------------------------------------------------
+
+def idempotency_headers(tenant_id: str, thread_id: str, key: str) -> dict:
+    """Standard header set required by the middleware.
+    Accepts short names (t1, thr1) or raw UUID strings.
+    """
+    t_uuid = TENANT_UUIDS.get(tenant_id, tenant_id)
+    th_uuid = THREAD_UUIDS.get(thread_id, thread_id)
+    return {
+        "tenant-id": t_uuid,
+        "Thread-Id": th_uuid,
+        "Idempotency-Key": key,
+    }
+
+def approve_body(tenant_id: str, thread_id: str) -> dict:
+    """JSON body required by the public approve/reject endpoints."""
+    return {
+        "tenant_id": TENANT_UUIDS.get(tenant_id, tenant_id),
+        "thread_id": THREAD_UUIDS.get(thread_id, thread_id),
+    }
+
+async def barrier_gather(coros, barrier: asyncio.Barrier):
+    """Wrap each coroutine (or zero-arg callable returning a coroutine) so they
+    all wait on the same barrier before executing.
+    Returns list of results in the original order.
+    """
+    async def wrapped(coro_or_factory):
+        await barrier.wait()
+        coro = coro_or_factory() if callable(coro_or_factory) and not hasattr(coro_or_factory, '__await__') else coro_or_factory
+        return await coro
+    return await asyncio.gather(*(wrapped(c) for c in coros))
+
+# ---------------------------------------------------------------------------
+# Test cases
+# ---------------------------------------------------------------------------
+
+@pytest.mark.asyncio
+async def test_double_approve_race(client: httpx.AsyncClient, async_session: AsyncSession):
+    tenant, thread, key = "t1", "thr1", "key-approve"
+    headers = idempotency_headers(tenant, thread, key)
+    body = approve_body(tenant, thread)
+
+    async def call():
+        return await client.post("/api/v1/hitl/approve", headers=headers, json=body)
+
+    # two concurrent calls
+    barrier = asyncio.Barrier(2)
+    responses = await barrier_gather([call(), call()], barrier)
+    statuses = {r.status_code for r in responses}
+    assert statuses == {202, 409}
+
+    # verify DB state
+    t_uuid = TENANT_UUIDS[tenant]
+    th_uuid = THREAD_UUIDS[thread]
+    res = await async_session.execute(
+        text(
+            "SELECT status FROM hitl_idempotency WHERE tenant_id=:t AND thread_id=:thr AND idempotency_key=:k"
+        ),
+        {"t": t_uuid, "thr": th_uuid, "k": key},
+    )
+    row = res.fetchone()
+    assert row and row[0] == "COMMITTED"
+
+    # exactly one outbox event for this thread
+    out_res = await async_session.execute(
+        text("SELECT COUNT(*) FROM outbox_events WHERE event_type='ExecutionApproved' AND thread_id=:thid"),
+        {"thid": th_uuid},
+    )
+    assert out_res.scalar_one() == 1
+
+
+@pytest.mark.asyncio
+async def test_double_reject_race(client: httpx.AsyncClient, async_session: AsyncSession):
+    tenant, thread, key = "t2", "thr2", "key-reject"
+    headers = idempotency_headers(tenant, thread, key)
+    body = approve_body(tenant, thread)
+
+    async def call():
+        return await client.post("/api/v1/hitl/reject", headers=headers, json=body)
+
+    barrier = asyncio.Barrier(2)
+    responses = await barrier_gather([call(), call()], barrier)
+    statuses = {r.status_code for r in responses}
+    assert statuses == {202, 409}
+
+    # DB state
+    t_uuid = TENANT_UUIDS[tenant]
+    th_uuid = THREAD_UUIDS[thread]
+    res = await async_session.execute(
+        text(
+            "SELECT status FROM hitl_idempotency WHERE tenant_id=:t AND thread_id=:thr AND idempotency_key=:k"
+        ),
+        {"t": t_uuid, "thr": th_uuid, "k": key},
+    )
+    row = res.fetchone()
+    assert row and row[0] == "COMMITTED"
+
+    out_res = await async_session.execute(
+        text("SELECT COUNT(*) FROM outbox_events WHERE event_type='ExecutionRejected' AND thread_id=:thid"),
+        {"thid": th_uuid},
+    )
+    assert out_res.scalar_one() == 1
+
+
+@pytest.mark.asyncio
+async def test_invalid_state_transition(client: httpx.AsyncClient, async_session: AsyncSession):
+    """Test that a second call with a COMMITTED idempotency key returns 409.
+    We first approve the execution (202) to get a COMMITTED idempotency row,
+    then call approve again with the same key to get 409.
+    """
+    tenant, thread, key = "t3", "thr3", "invalid-key"
+    t_uuid = TENANT_UUIDS[tenant]
+    th_uuid = THREAD_UUIDS[thread]
+
+    headers = idempotency_headers(tenant, thread, key)
+    body = approve_body(tenant, thread)
+
+    # First call — should succeed (202) and create a COMMITTED row + outbox event
+    resp_first = await client.post("/api/v1/hitl/approve", headers=headers, json=body)
+    assert resp_first.status_code == 202
+
+    # Second call with SAME key — idempotency middleware returns 409 (already COMMITTED)
+    resp = await client.post("/api/v1/hitl/approve", headers=headers, json=body)
+    assert resp.status_code == 409
+
+    # Only one idempotency row (COMMITTED)
+    cnt = await async_session.execute(
+        text(
+            "SELECT COUNT(*) FROM hitl_idempotency WHERE tenant_id=:t AND thread_id=:thr AND idempotency_key=:k"
+        ),
+        {"t": t_uuid, "thr": th_uuid, "k": key},
+    )
+    assert cnt.scalar_one() == 1
+
+    # Exactly one outbox event for this execution (from the first approve)
+    out_cnt = await async_session.execute(
+        text("SELECT COUNT(*) FROM outbox_events WHERE thread_id=:thid AND event_type='ExecutionApproved'"),
+        {"thid": th_uuid},
+    )
+    assert out_cnt.scalar_one() == 1
+
+
+@pytest.mark.asyncio
+async def test_retry_after_failure(client: httpx.AsyncClient, async_session: AsyncSession, monkeypatch):
+    tenant, thread, key = "t4", "thr4", "retry-key"
+    t_uuid = TENANT_UUIDS[tenant]
+    th_uuid = THREAD_UUIDS[thread]
+    headers = idempotency_headers(tenant, thread, key)
+    body = approve_body(tenant, thread)
+
+    # Force the lifecycle_manager to raise on the first call
+    from core import lifecycle
+    async def failing_approve(*_, **__):
+        raise Exception("simulated failure")
+    monkeypatch.setattr(lifecycle.lifecycle_manager, "approve_execution", failing_approve)
+
+    # First request – expected failure, status becomes FAILED
+    resp1 = await client.post("/api/v1/hitl/approve", headers=headers, json=body)
+    assert resp1.status_code == 500  # internal error propagated
+
+    # Verify FAILED state
+    res = await async_session.execute(
+        text(
+            "SELECT status FROM hitl_idempotency WHERE tenant_id=:t AND thread_id=:thr AND idempotency_key=:k"
+        ),
+        {"t": t_uuid, "thr": th_uuid, "k": key},
+    )
+    row = res.fetchone()
+    assert row and row[0] == "FAILED"
+
+    # Restore normal behavior for retry (undo monkeypatch)
+    monkeypatch.undo()
+
+    # Second request – should succeed (FAILED rows are retried by the middleware)
+    resp2 = await client.post("/api/v1/hitl/approve", headers=headers, json=body)
+    assert resp2.status_code == 202
+
+    # Final state COMMITTED
+    final = await async_session.execute(
+        text(
+            "SELECT status FROM hitl_idempotency WHERE tenant_id=:t AND thread_id=:thr AND idempotency_key=:k"
+        ),
+        {"t": t_uuid, "thr": th_uuid, "k": key},
+    )
+    assert final.fetchone()[0] == "COMMITTED"
+
+    # Exactly one outbox event for this thread
+    out = await async_session.execute(
+        text("SELECT COUNT(*) FROM outbox_events WHERE event_type='ExecutionApproved' AND thread_id=:thid"),
+        {"thid": th_uuid},
+    )
+    assert out.scalar_one() == 1
+
+
+# Matched pairs: each thread_id has exactly one valid tenant_id in the seeded DB
+MATCHED_PAIRS = [(f"t{i}", f"thr{i}") for i in range(1, 21)]
+
+@pytest.mark.asyncio
+async def test_light_concurrent_load(client: httpx.AsyncClient, async_session: AsyncSession):
+    """Run a deterministic light concurrency test (80 requests) with mixed approve/reject.
+    Uses only seeded (tenant, thread) pairs so lifecycle_manager can find the execution.
+    Invariants are verified automatically by the autouse fixture after the test.
+    """
+    total_requests = 80
+    barrier = asyncio.Barrier(total_requests)
+
+    async def make_call(tenant: str, thread: str, key: str, action: str):
+        headers = idempotency_headers(tenant, thread, key)
+        body = approve_body(tenant, thread)
+        url = "/api/v1/hitl/approve" if action == "approve" else "/api/v1/hitl/reject"
+        return await client.post(url, headers=headers, json=body)
+
+    coros = []
+    for i in range(total_requests):
+        tenant, thread = random.choice(MATCHED_PAIRS)
+        key = f"load-{i}"
+        action = random.choice(["approve", "reject"])
+        coros.append(lambda t=tenant, th=thread, k=key, a=action: make_call(t, th, k, a))
+
+    responses = await barrier_gather(coros, barrier)
+    for r in responses:
+        assert r.status_code in {202, 409}
+
+
+@pytest.mark.asyncio
+async def test_medium_concurrent_load(client: httpx.AsyncClient, async_session: AsyncSession):
+    """Run a moderate concurrency stress test (120 requests) with mixed actions.
+    Uses only seeded (tenant, thread) pairs so lifecycle_manager can find the execution.
+    Invariants are verified automatically by the autouse fixture after the test.
+    """
+    total_requests = 120
+    barrier = asyncio.Barrier(total_requests)
+
+    async def make_call(tenant: str, thread: str, key: str, action: str):
+        headers = idempotency_headers(tenant, thread, key)
+        body = approve_body(tenant, thread)
+        url = "/api/v1/hitl/approve" if action == "approve" else "/api/v1/hitl/reject"
+        return await client.post(url, headers=headers, json=body)
+
+    coros = []
+    for i in range(total_requests):
+        tenant, thread = random.choice(MATCHED_PAIRS)
+        key = f"load-{i}"
+        action = random.choice(["approve", "reject"])
+        coros.append(lambda t=tenant, th=thread, k=key, a=action: make_call(t, th, k, a))
+
+    responses = await barrier_gather(coros, barrier)
+    for r in responses:
+        assert r.status_code in {202, 409}
+
+
+@pytest.mark.asyncio
+async def test_heavy_concurrent_load(client: httpx.AsyncClient, async_session: AsyncSession):
+    """200 concurrent requests — no 500s allowed."""
+    total_requests = 200
+    barrier = asyncio.Barrier(total_requests)
+
+    async def make_call(tenant: str, thread: str, key: str, action: str):
+        headers = idempotency_headers(tenant, thread, key)
+        body = approve_body(tenant, thread)
+        url = "/api/v1/hitl/approve" if action == "approve" else "/api/v1/hitl/reject"
+        return await client.post(url, headers=headers, json=body)
+
+    coros = []
+    for i in range(total_requests):
+        tenant, thread = random.choice(MATCHED_PAIRS)
+        key = f"heavy-{i}"
+        action = random.choice(["approve", "reject"])
+        coros.append(lambda t=tenant, th=thread, k=key, a=action: make_call(t, th, k, a))
+
+    responses = await barrier_gather(coros, barrier)
+    for r in responses:
+        assert r.status_code in {202, 409}
+
+
+@pytest.mark.asyncio
+async def test_stress_concurrent_load(client: httpx.AsyncClient, async_session: AsyncSession):
+    """500 concurrent requests — no 500s allowed."""
+    total_requests = 500
+    barrier = asyncio.Barrier(total_requests)
+
+    async def make_call(tenant: str, thread: str, key: str, action: str):
+        headers = idempotency_headers(tenant, thread, key)
+        body = approve_body(tenant, thread)
+        url = "/api/v1/hitl/approve" if action == "approve" else "/api/v1/hitl/reject"
+        return await client.post(url, headers=headers, json=body)
+
+    coros = []
+    for i in range(total_requests):
+        tenant, thread = random.choice(MATCHED_PAIRS)
+        key = f"stress-{i}"
+        action = random.choice(["approve", "reject"])
+        coros.append(lambda t=tenant, th=thread, k=key, a=action: make_call(t, th, k, a))
+
+    responses = await barrier_gather(coros, barrier)
+    for r in responses:
+        assert r.status_code in {202, 409}

aegis_idempotency-0.1.0/tests/test_sdk_client.py

@@ -0,0 +1,232 @@
+"""Unit tests for aegis_hitl.AegisClient — no server, no Docker."""
+import asyncio
+import pytest
+import httpx
+from aegis_hitl import AegisClient
+
+
+def _make_transport(status: int = 202) -> httpx.MockTransport:
+    """Return a MockTransport that always responds with the given status."""
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(status, json={"ok": True})
+    return httpx.MockTransport(handler)
+
+
+# ── approve ────────────────────────────────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_approve_posts_to_correct_endpoint():
+    captured = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["path"] = request.url.path
+        captured["headers"] = dict(request.headers)
+        return httpx.Response(202, json={"ok": True})
+
+    transport = httpx.MockTransport(handler)
+    mock_client = httpx.AsyncClient(transport=transport, base_url="http://test")
+
+    async with AegisClient(tenant_id="t1", thread_id="th1", client=mock_client) as client:
+        response = await client.approve("key-001")
+
+    assert response.status_code == 202
+    assert captured["path"] == "/api/v1/hitl/approve"
+    assert captured["headers"]["tenant-id"] == "t1"
+    assert captured["headers"]["thread-id"] == "th1"
+    assert captured["headers"]["idempotency-key"] == "key-001"
+    assert "x-request-id" in captured["headers"]
+
+
+# ── reject ─────────────────────────────────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_reject_posts_to_correct_endpoint():
+    captured = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["path"] = request.url.path
+        return httpx.Response(202, json={"ok": True})
+
+    transport = httpx.MockTransport(handler)
+    mock_client = httpx.AsyncClient(transport=transport, base_url="http://test")
+
+    async with AegisClient(tenant_id="t1", thread_id="th1", client=mock_client) as client:
+        response = await client.reject("key-002")
+
+    assert response.status_code == 202
+    assert captured["path"] == "/api/v1/hitl/reject"
+
+
+# ── execute ────────────────────────────────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_execute_approve_dispatches_correctly():
+    captured = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["path"] = request.url.path
+        return httpx.Response(202, json={"ok": True})
+
+    transport = httpx.MockTransport(handler)
+    mock_client = httpx.AsyncClient(transport=transport, base_url="http://test")
+
+    async with AegisClient(tenant_id="t1", thread_id="th1", client=mock_client) as client:
+        await client.execute("approve", "key-003")
+
+    assert captured["path"] == "/api/v1/hitl/approve"
+
+
+@pytest.mark.asyncio
+async def test_execute_reject_dispatches_correctly():
+    captured = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["path"] = request.url.path
+        return httpx.Response(202, json={"ok": True})
+
+    transport = httpx.MockTransport(handler)
+    mock_client = httpx.AsyncClient(transport=transport, base_url="http://test")
+
+    async with AegisClient(tenant_id="t1", thread_id="th1", client=mock_client) as client:
+        await client.execute("reject", "key-004")
+
+    assert captured["path"] == "/api/v1/hitl/reject"
+
+
+@pytest.mark.asyncio
+async def test_execute_invalid_action_raises_value_error():
+    mock_client = httpx.AsyncClient(
+        transport=_make_transport(), base_url="http://test"
+    )
+    async with AegisClient(tenant_id="t1", thread_id="th1", client=mock_client) as client:
+        with pytest.raises(ValueError, match="approve.*reject"):
+            await client.execute("delete", "key-005")
+
+
+# ── tenant/thread resolution ───────────────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_per_call_tenant_thread_overrides_constructor():
+    captured = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        captured["tenant"] = request.headers.get("tenant-id")
+        captured["thread"] = request.headers.get("thread-id")
+        return httpx.Response(202, json={"ok": True})
+
+    transport = httpx.MockTransport(handler)
+    mock_client = httpx.AsyncClient(transport=transport, base_url="http://test")
+
+    async with AegisClient(tenant_id="default-t", thread_id="default-th", client=mock_client) as client:
+        await client.approve("key-006", tenant_id="override-t", thread_id="override-th")
+
+    assert captured["tenant"] == "override-t"
+    assert captured["thread"] == "override-th"
+
+
+@pytest.mark.asyncio
+async def test_missing_tenant_id_raises_value_error():
+    mock_client = httpx.AsyncClient(
+        transport=_make_transport(), base_url="http://test"
+    )
+    async with AegisClient(thread_id="th1", client=mock_client) as client:
+        with pytest.raises(ValueError, match="tenant_id"):
+            await client.approve("key-007")
+
+
+@pytest.mark.asyncio
+async def test_missing_thread_id_raises_value_error():
+    mock_client = httpx.AsyncClient(
+        transport=_make_transport(), base_url="http://test"
+    )
+    async with AegisClient(tenant_id="t1", client=mock_client) as client:
+        with pytest.raises(ValueError, match="thread_id"):
+            await client.approve("key-008")
+
+
+# ── X-Request-Id generation ────────────────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_x_request_id_is_auto_generated():
+    ids = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        ids.append(request.headers.get("x-request-id"))
+        return httpx.Response(202, json={"ok": True})
+
+    transport = httpx.MockTransport(handler)
+    mock_client = httpx.AsyncClient(transport=transport, base_url="http://test")
+
+    async with AegisClient(tenant_id="t1", thread_id="th1", client=mock_client) as client:
+        await client.approve("key-009")
+        await client.approve("key-010")
+
+    assert ids[0] is not None
+    assert ids[1] is not None
+    assert ids[0] != ids[1]  # each call generates a unique request-id
+
+
+# ── injected client lifecycle ──────────────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_injected_client_not_closed_on_exit():
+    """AegisClient must NOT close an externally-provided httpx.AsyncClient."""
+    transport = _make_transport()
+    external = httpx.AsyncClient(transport=transport, base_url="http://test")
+
+    async with AegisClient(tenant_id="t1", thread_id="th1", client=external) as client:
+        await client.approve("key-011")
+
+    # external client must still be usable after AegisClient exits
+    assert not external.is_closed
+    await external.aclose()
+
+
+# ── backoff / retry ────────────────────────────────────────────────────────────
+
+@pytest.mark.asyncio
+async def test_backoff_retries_on_5xx():
+    """Client retries up to max_retries times on 5xx responses."""
+    call_count = 0
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        nonlocal call_count
+        call_count += 1
+        if call_count < 3:
+            return httpx.Response(500, json={"error": "server error"})
+        return httpx.Response(202, json={"ok": True})
+
+    transport = httpx.MockTransport(handler)
+    mock_client = httpx.AsyncClient(transport=transport, base_url="http://test")
+
+    async with AegisClient(
+        tenant_id="t1", thread_id="th1", client=mock_client, max_retries=3
+    ) as client:
+        import unittest.mock
+        with unittest.mock.patch("aegis_hitl.client.asyncio.sleep"):
+            response = await client.approve("key-backoff-1")
+
+    assert response.status_code == 202
+    assert call_count == 3  # failed twice, succeeded on third attempt
+
+
+@pytest.mark.asyncio
+async def test_no_retry_on_4xx():
+    """Client does NOT retry on 4xx (e.g. 409 Conflict is a business response)."""
+    call_count = 0
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        nonlocal call_count
+        call_count += 1
+        return httpx.Response(409, json={"error": "duplicate"})
+
+    transport = httpx.MockTransport(handler)
+    mock_client = httpx.AsyncClient(transport=transport, base_url="http://test")
+
+    async with AegisClient(
+        tenant_id="t1", thread_id="th1", client=mock_client, max_retries=3
+    ) as client:
+        response = await client.approve("key-backoff-2")
+
+    assert response.status_code == 409
+    assert call_count == 1  # no retry on 4xx