microcoreos 0.3.2__tar.gz → 0.4.0__tar.gz

{microcoreos-0.3.2 → microcoreos-0.4.0}/AI_CONTEXT.md

@@ -63,6 +63,10 @@ HTTP Server Tool (http):
             - context.set_cookie(key, value, max_age=3600, ...): Set secure response cookie.
             - context.set_header(key, value): Add custom response header.
             - context.set_binary_response(content: bytes, media_type: str): Return raw file.
+            - context.client_ip: Best-effort caller IP (property). Raw signal only — the
+              plugin decides what to do with it (e.g. state.increment() keyed by IP for
+              an identity-aware business rule). Never security-authoritative on its own;
+              see context.py's client_ip docstring for the trust order and its limits.
         - RESPONSE CONTRACT:
             - Standard: return {"success": bool, "data": ..., "error": ...}
             - WARNING: All values in 'data' must be JSON-serializable. Pydantic model 

{microcoreos-0.3.2 → microcoreos-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: microcoreos
-Version: 0.3.2
+Version: 0.4.0
 Summary: Atomic Microkernel Architecture optimized for AI-Driven Development
 License: MIT
 License-File: LICENSE
@@ -204,9 +204,9 @@ The system scans all tools, plugins, domains, events, and models — then writes
 
 A Tool is identified by its `name` property. The SQLite tool and the PostgreSQL tool both expose the same API (`query`, `execute`, `transaction`, `health_check`) and both use `$1, $2` placeholders. To switch databases:
 
-1. Change `name = "db"` in the SQLite tool to `name = "sqlite"`
-2. Change `name = "postgresql"` in the PostgreSQL tool to `name = "db"`
-3. Plugins don't change a single line.
+1. Move `tools/sqlite` to `extras/available_tools/sqlite`
+2. Move `extras/available_tools/postgresql` to `tools/postgresql`
+3. Plugins don't change a single line. Both tools expose the exact same `db` API.
 
 Migrations are the honest exception: the `db` tool is not an ORM — SQL files run
 **verbatim** on the active engine (no dialect translation), so an engine swap includes

{microcoreos-0.3.2 → microcoreos-0.4.0}/README.md

@@ -163,9 +163,9 @@ The system scans all tools, plugins, domains, events, and models — then writes
 
 A Tool is identified by its `name` property. The SQLite tool and the PostgreSQL tool both expose the same API (`query`, `execute`, `transaction`, `health_check`) and both use `$1, $2` placeholders. To switch databases:
 
-1. Change `name = "db"` in the SQLite tool to `name = "sqlite"`
-2. Change `name = "postgresql"` in the PostgreSQL tool to `name = "db"`
-3. Plugins don't change a single line.
+1. Move `tools/sqlite` to `extras/available_tools/sqlite`
+2. Move `extras/available_tools/postgresql` to `tools/postgresql`
+3. Plugins don't change a single line. Both tools expose the exact same `db` API.
 
 Migrations are the honest exception: the `db` tool is not an ORM — SQL files run
 **verbatim** on the active engine (no dialect translation), so an engine swap includes

microcoreos-0.4.0/extras/available_domains/users/migrations/001_create_users.sql

@@ -0,0 +1,11 @@
+-- users table (auth domain). Written explicitly for SQLite default.
+-- On a PostgreSQL swap, rewrite the autoincrement primary key:
+--   Change "INTEGER PRIMARY KEY" -> "INTEGER PRIMARY KEY GENERATED BY DEFAULT AS IDENTITY"
+--   (or "SERIAL PRIMARY KEY"). See docs/ELASTIC_DEPLOYMENT.md Stage 1.
+CREATE TABLE IF NOT EXISTS users (
+    id            INTEGER PRIMARY KEY,
+    name          TEXT    NOT NULL,
+    email         TEXT    NOT NULL UNIQUE,
+    password_hash TEXT    NOT NULL,
+    roles         TEXT    NOT NULL DEFAULT '["user"]'
+);

{microcoreos-0.3.2 → microcoreos-0.4.0}/extras/available_tools/postgresql/postgresql_tool.py

@@ -39,12 +39,35 @@ ERROR CONTRACT (part of the gold standard — any db tool MUST match it):
 PLACEHOLDERS: PostgreSQL uses $1, $2, $3... (NOT '?' like SQLite).
 """
 
+import asyncio
+import json
 import os
 import re
-import asyncio
+
 import asyncpg
+
 from microcoreos import BaseTool, ToolUnavailableError
 
+_CREATE_TABLE_RE = re.compile(
+    r"CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?[\"'`]?(\w+)[\"'`]?", re.IGNORECASE
+)
+
+
+async def _init_postgres_connection(conn: asyncpg.Connection) -> None:
+    """Register JSON/JSONB codecs so asyncpg automatically serializes/deserializes Python dicts and lists."""
+    await conn.set_type_codec(
+        "json",
+        encoder=json.dumps,
+        decoder=json.loads,
+        schema="pg_catalog",
+    )
+    await conn.set_type_codec(
+        "jsonb",
+        encoder=json.dumps,
+        decoder=json.loads,
+        schema="pg_catalog",
+    )
+
 
 # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 # EXCEPTIONS
@@ -334,7 +357,7 @@ class PostgresqlTool(BaseTool):
 
     @property
     def name(self) -> str:
-        return "postgresql"
+        return "db"
 
     # ─── CONSTRUCTOR ──────────────────────────────────────
     #
@@ -377,6 +400,7 @@ class PostgresqlTool(BaseTool):
                     max_size=self._max_pool,
                     timeout=self._connect_timeout,
                     command_timeout=self._command_timeout,
+                    init=_init_postgres_connection,
                 ),
                 timeout=self._connect_timeout,
             )
@@ -483,6 +507,8 @@ class PostgresqlTool(BaseTool):
             print(f"  [Migration] ⚠️  Circular dependency detected: {e}")
             ordered_keys = sorted(migrations.keys())
 
+        live_schema = set((await self.describe_schema()).keys())
+
         # ── 3. Apply in topological order ───────────────────────────────
         for key in ordered_keys:
             if key not in migrations:
@@ -492,20 +518,29 @@ class PostgresqlTool(BaseTool):
             domain = info["domain"]
             filename = info["filename"]
 
+            with open(info["path"], "r", encoding="utf-8") as f:
+                lines = f.readlines()
+                sql_script = "\n".join(line for line in lines if not line.strip().startswith("--"))
+
+            declared_tables = _CREATE_TABLE_RE.findall(sql_script)
+
             # Check if already applied
             already_applied = await self.query_one(
                 "SELECT 1 FROM _migrations_history WHERE domain = $1 AND filename = $2",
                 [domain, filename],
             )
             if already_applied:
-                continue
+                missing_tables = [t for t in declared_tables if t not in live_schema]
+                if not missing_tables:
+                    continue
+                print(f"  [Migration] ⚠️ Table(s) {missing_tables} declared in {key} missing from DB despite history record. Repairing...")
+                await self.execute(
+                    "DELETE FROM _migrations_history WHERE domain = $1 AND filename = $2",
+                    [domain, filename],
+                )
 
             print(f"  [Migration] Applying {key}...")
 
-            with open(info["path"], "r", encoding="utf-8") as f:
-                lines = f.readlines()
-                sql_script = "\n".join(line for line in lines if not line.strip().startswith("--"))
-
             # Each migration in its own transaction
             async with self.transaction() as tx:
                 # asyncpg support multiple statements in execute() when no params are provided
@@ -519,6 +554,7 @@ class PostgresqlTool(BaseTool):
                 except Exception as e:
                     raise DatabaseError(f"Migration failed for {key}: {e}", **_classify_error(e)) from e
 
+            live_schema.update(declared_tables)
             print(f"  [Migration] ✅ Applied {key}")
 
     # ─── LIFECYCLE: shutdown() ────────────────────────────

{microcoreos-0.3.2 → microcoreos-0.4.0}/extras/available_tools/postgresql/tests/postgresql_describe_schema_test.py

@@ -52,7 +52,7 @@ def pg_env(monkeypatch):
     monkeypatch.setenv("PG_PORT", "5432")
     monkeypatch.setenv("PG_USER", "postgres")
     monkeypatch.setenv("PG_PASSWORD", "postgres")
-    monkeypatch.setenv("PG_DATABASE", "microcoreos")
+    monkeypatch.setenv("PG_DATABASE", "microcoreos_test")
     monkeypatch.setenv("DB_AUTO_MIGRATE", "false")
 
 @pytest.fixture
@@ -60,11 +60,30 @@ async def db():
     tool = PostgresqlTool()
     try:
         await tool.setup()
-    except DatabaseConnectionError:
-        pytest.skip(
-            "PostgreSQL not available — "
-            "docker compose -f dev_infra/docker-compose.yml up -d postgres"
-        )
+    except DatabaseConnectionError as e:
+        if "does not exist" in str(e).lower():
+            try:
+                import os
+                import asyncpg
+                host = os.getenv("PG_HOST", "localhost")
+                port = int(os.getenv("PG_PORT", "5432"))
+                user = os.getenv("PG_USER", "postgres")
+                password = os.getenv("PG_PASSWORD", "postgres")
+                dbname = os.getenv("PG_DATABASE", "microcoreos_test")
+                conn = await asyncpg.connect(host=host, port=port, user=user, password=password, database="postgres")
+                await conn.execute(f'CREATE DATABASE "{dbname}"')
+                await conn.close()
+                await tool.setup()
+            except Exception:
+                pytest.skip(
+                    "PostgreSQL not available — "
+                    "docker compose -f dev_infra/docker-compose.yml up -d postgres"
+                )
+        else:
+            pytest.skip(
+                "PostgreSQL not available — "
+                "docker compose -f dev_infra/docker-compose.yml up -d postgres"
+            )
     yield tool
     await tool.shutdown()
 

{microcoreos-0.3.2 → microcoreos-0.4.0}/extras/available_tools/postgresql/tests/postgresql_tool_test.py

@@ -1,3 +1,4 @@
+import os
 import pytest
 
 
@@ -28,7 +29,7 @@ def pg_env(monkeypatch):
     monkeypatch.setenv("PG_PORT", "5432")
     monkeypatch.setenv("PG_USER", "postgres")
     monkeypatch.setenv("PG_PASSWORD", "postgres")
-    monkeypatch.setenv("PG_DATABASE", "microcoreos")
+    monkeypatch.setenv("PG_DATABASE", "microcoreos_test")
 
 # ── Unit tests (no Docker) ──────────────────────────────────────────────────
 
@@ -52,7 +53,25 @@ def test_parse_empty():
 @pytest.fixture
 async def tool():
     t = PostgresqlTool()
-    await t.setup()
+    try:
+        await t.setup()
+    except Exception as e:
+        if "does not exist" in str(e).lower():
+            try:
+                import asyncpg
+                host = os.getenv("PG_HOST", "localhost")
+                port = int(os.getenv("PG_PORT", "5432"))
+                user = os.getenv("PG_USER", "postgres")
+                password = os.getenv("PG_PASSWORD", "postgres")
+                dbname = os.getenv("PG_DATABASE", "microcoreos_test")
+                conn = await asyncpg.connect(host=host, port=port, user=user, password=password, database="postgres")
+                await conn.execute(f'CREATE DATABASE "{dbname}"')
+                await conn.close()
+                await t.setup()
+            except Exception as inner_e:
+                pytest.skip(f"PostgreSQL server unreachable: {inner_e}")
+        else:
+            pytest.skip(f"PostgreSQL server unreachable: {e}")
     yield t
     await t.execute("DROP TABLE IF EXISTS _test")
     await t.shutdown()

{microcoreos-0.3.2 → microcoreos-0.4.0}/microcoreos/scaffold.py

@@ -216,15 +216,89 @@ Starter pytest fixtures for MicroCoreOS application tests.
 Auto-generated by `microcoreos new`.
 \"\"\"
 
+import inspect
+from pathlib import Path
 from unittest.mock import AsyncMock, MagicMock
 import pytest
 
+from tests.helpers.active_db import active_db as _active_db
+
+_PROJECT_ROOT = Path(__file__).resolve().parent
+_MIGRATION_ROOTS = (
+    _PROJECT_ROOT / "domains",
+    _PROJECT_ROOT / "extras" / "available_domains",
+)
+
+
+def _migrations_dir(domain: str) -> Path | None:
+    for root in _MIGRATION_ROOTS:
+        candidate = root / domain / "migrations"
+        if candidate.is_dir():
+            return candidate
+    return None
+
+
+async def _lifecycle(tool, method: str):
+    fn = getattr(tool, method, None)
+    if fn is None:
+        return
+    result = fn()
+    if inspect.isawaitable(result):
+        await result
+
 
 @pytest.fixture
 def anyio_backend():
     return "asyncio"
 
 
+@pytest.fixture
+async def db(request, monkeypatch):
+    marker = request.node.get_closest_marker("migrations")
+    names = marker.args if marker else ()
+    resolved = {name: _migrations_dir(name) for name in names}
+    dirs = [d for d in resolved.values() if d is not None]
+    async with _active_db(monkeypatch, *dirs) as tool:
+        yield tool
+
+
+@pytest.fixture
+async def event_bus():
+    from tools.event_bus.event_bus_tool import EventBusTool
+    tool = EventBusTool()
+    await _lifecycle(tool, "setup")
+    yield tool
+    await _lifecycle(tool, "shutdown")
+
+
+@pytest.fixture
+async def auth(monkeypatch):
+    from extras.available_tools.auth.auth_tool import AuthTool
+    monkeypatch.setenv("AUTH_SECRET_KEY", "test-secret-key-0123456789abcdefghij")
+    tool = AuthTool()
+    await _lifecycle(tool, "setup")
+    yield tool
+    await _lifecycle(tool, "shutdown")
+
+
+@pytest.fixture
+async def config():
+    from tools.config.config_tool import ConfigTool
+    tool = ConfigTool()
+    await _lifecycle(tool, "setup")
+    yield tool
+    await _lifecycle(tool, "shutdown")
+
+
+@pytest.fixture
+async def state():
+    from tools.state.state_tool import StateTool
+    tool = StateTool()
+    await _lifecycle(tool, "setup")
+    yield tool
+    await _lifecycle(tool, "shutdown")
+
+
 @pytest.fixture
 def mock_logger():
     logger = MagicMock()

{microcoreos-0.3.2 → microcoreos-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "microcoreos"
-version = "0.3.2"
+version = "0.4.0"
 description = "Atomic Microkernel Architecture optimized for AI-Driven Development"
 license = {text = "MIT"}
 readme = "README.md"

{microcoreos-0.3.2 → microcoreos-0.4.0}/tests/helpers/active_db.py

@@ -58,7 +58,7 @@ _TEST_ENV = {
     "PG_PORT": "5432",
     "PG_USER": "postgres",
     "PG_PASSWORD": "postgres",
-    "PG_DATABASE": "microcoreos",
+    "PG_DATABASE": "microcoreos_test",
     # Tests apply the migrations they need explicitly (below), so boot-time
     # auto-migration would only add unrelated domains' tables.
     "DB_AUTO_MIGRATE": "false",
@@ -134,7 +134,23 @@ async def active_db(monkeypatch, *migration_dirs: Path):
     try:
         await tool.setup()
     except ToolUnavailableError as e:
-        pytest.skip(f"active db tool {tool_cls.__name__} is unreachable: {e}")
+        if "does not exist" in str(e).lower() and tool_cls.__name__ == "PostgresqlTool":
+            try:
+                import os
+                import asyncpg
+                host = os.getenv("PG_HOST", "localhost")
+                port = int(os.getenv("PG_PORT", "5432"))
+                user = os.getenv("PG_USER", "postgres")
+                password = os.getenv("PG_PASSWORD", "postgres")
+                dbname = os.getenv("PG_DATABASE", "microcoreos_test")
+                conn = await asyncpg.connect(host=host, port=port, user=user, password=password, database="postgres")
+                await conn.execute(f'CREATE DATABASE "{dbname}"')
+                await conn.close()
+                await tool.setup()
+            except Exception:
+                pytest.skip(f"active db tool {tool_cls.__name__} is unreachable: {e}")
+        else:
+            pytest.skip(f"active db tool {tool_cls.__name__} is unreachable: {e}")
 
     tables: list[str] = []
     try:

{microcoreos-0.3.2 → microcoreos-0.4.0}/tests/tools/db/test_db_parity.py

@@ -47,16 +47,35 @@ async def db(request, monkeypatch):
     monkeypatch.setenv("PG_PORT", "5432")
     monkeypatch.setenv("PG_USER", "postgres")
     monkeypatch.setenv("PG_PASSWORD", "postgres")
-    monkeypatch.setenv("PG_DATABASE", "microcoreos")
+    monkeypatch.setenv("PG_DATABASE", "microcoreos_test")
     monkeypatch.setenv("DB_AUTO_MIGRATE", "false")
     tool = PostgresqlTool()
     try:
         await tool.setup()
-    except PGConnectionError:
-        pytest.skip(
-            "PostgreSQL not available — "
-            "docker compose -f dev_infra/docker-compose.yml up -d postgres"
-        )
+    except PGConnectionError as e:
+        if "does not exist" in str(e).lower():
+            try:
+                import os
+                import asyncpg
+                host = os.getenv("PG_HOST", "localhost")
+                port = int(os.getenv("PG_PORT", "5432"))
+                user = os.getenv("PG_USER", "postgres")
+                password = os.getenv("PG_PASSWORD", "postgres")
+                dbname = os.getenv("PG_DATABASE", "microcoreos_test")
+                conn = await asyncpg.connect(host=host, port=port, user=user, password=password, database="postgres")
+                await conn.execute(f'CREATE DATABASE "{dbname}"')
+                await conn.close()
+                await tool.setup()
+            except Exception:
+                pytest.skip(
+                    "PostgreSQL not available — "
+                    "docker compose -f dev_infra/docker-compose.yml up -d postgres"
+                )
+        else:
+            pytest.skip(
+                "PostgreSQL not available — "
+                "docker compose -f dev_infra/docker-compose.yml up -d postgres"
+            )
     yield tool
     await tool.execute("DROP TABLE IF EXISTS _parity")
     await tool.shutdown()
@@ -229,17 +248,37 @@ async def both_engines(monkeypatch):
     monkeypatch.setenv("PG_PORT", "5432")
     monkeypatch.setenv("PG_USER", "postgres")
     monkeypatch.setenv("PG_PASSWORD", "postgres")
-    monkeypatch.setenv("PG_DATABASE", "microcoreos")
+    monkeypatch.setenv("PG_DATABASE", "microcoreos_test")
     monkeypatch.setenv("DB_AUTO_MIGRATE", "false")
     pg_tool = PostgresqlTool()
     try:
         await pg_tool.setup()
-    except PGConnectionError:
-        await sqlite_tool.shutdown()
-        pytest.skip(
-            "PostgreSQL not available — "
-            "docker compose -f dev_infra/docker-compose.yml up -d postgres"
-        )
+    except PGConnectionError as e:
+        if "does not exist" in str(e).lower():
+            try:
+                import os
+                import asyncpg
+                host = os.getenv("PG_HOST", "localhost")
+                port = int(os.getenv("PG_PORT", "5432"))
+                user = os.getenv("PG_USER", "postgres")
+                password = os.getenv("PG_PASSWORD", "postgres")
+                dbname = os.getenv("PG_DATABASE", "microcoreos_test")
+                conn = await asyncpg.connect(host=host, port=port, user=user, password=password, database="postgres")
+                await conn.execute(f'CREATE DATABASE "{dbname}"')
+                await conn.close()
+                await pg_tool.setup()
+            except Exception:
+                await sqlite_tool.shutdown()
+                pytest.skip(
+                    "PostgreSQL not available — "
+                    "docker compose -f dev_infra/docker-compose.yml up -d postgres"
+                )
+        else:
+            await sqlite_tool.shutdown()
+            pytest.skip(
+                "PostgreSQL not available — "
+                "docker compose -f dev_infra/docker-compose.yml up -d postgres"
+            )
 
     await pg_tool.execute("DROP TABLE IF EXISTS _parity_schema")
     for tool in (sqlite_tool, pg_tool):

{microcoreos-0.3.2 → microcoreos-0.4.0}/tests/tools/http_server/test_http_pipeline.py

@@ -8,6 +8,7 @@ from tools.http_server.pipeline import (
     _process_request,
     _extract_bearer_token,
     _extract_ws_token,
+    _extract_client_ip,
 )
 from tools.http_server.context import HttpContext
 from pydantic import BaseModel
@@ -62,6 +63,62 @@ async def test_extract_bearer_token_csrf_block():
     assert token == "cookie_jwt"
 
 
+def test_extract_client_ip_trust_order():
+    # 1. Cf-Connecting-Ip wins even if the other two are also present.
+    req = MagicMock(spec=Request)
+    req.headers = Headers({
+        "Cf-Connecting-Ip": "203.0.113.7",
+        "X-Forwarded-For": "198.51.100.1, 10.0.0.1",
+    })
+    req.client = MagicMock(host="10.0.0.99")
+    assert _extract_client_ip(req) == "203.0.113.7"
+
+    # 2. No Cf-Connecting-Ip -> first hop of X-Forwarded-For.
+    req = MagicMock(spec=Request)
+    req.headers = Headers({"X-Forwarded-For": "198.51.100.1, 10.0.0.1"})
+    req.client = MagicMock(host="10.0.0.99")
+    assert _extract_client_ip(req) == "198.51.100.1"
+
+    # 3. Neither header -> the direct TCP peer.
+    req = MagicMock(spec=Request)
+    req.headers = Headers({})
+    req.client = MagicMock(host="10.0.0.99")
+    assert _extract_client_ip(req) == "10.0.0.99"
+
+    # 4. No signal at all (request.client itself is None) -> None, not a crash.
+    req = MagicMock(spec=Request)
+    req.headers = Headers({})
+    req.client = None
+    assert _extract_client_ip(req) is None
+
+
+@pytest.mark.anyio
+async def test_process_request_exposes_client_ip_to_handler():
+    req = MagicMock(spec=Request)
+    req.query_params = {}
+    req.path_params = {}
+    req.headers = Headers({"Cf-Connecting-Ip": "203.0.113.7"})
+    req.method = "GET"
+    req.url.path = "/whoami"
+    req.client = MagicMock(host="10.0.0.99")
+
+    seen_ip = {}
+
+    async def handler(data, ctx: HttpContext):
+        seen_ip["value"] = ctx.client_ip
+        return {"success": True}
+
+    await _process_request(
+        request=req,
+        body_data=None,
+        handler=handler,
+        auth_validator=None,
+        paused_owners=set(),
+    )
+
+    assert seen_ip["value"] == "203.0.113.7"
+
+
 @pytest.mark.anyio
 async def test_process_request_redirect_response():
     req = MagicMock(spec=Request)

{microcoreos-0.3.2 → microcoreos-0.4.0}/tools/http_server/context.py

@@ -22,11 +22,34 @@ class HttpContext:
     All mutations are applied to the response before it is sent to the client.
     """
 
-    def __init__(self) -> None:
+    def __init__(self, client_ip: str | None = None) -> None:
         self._status_code: int = 200
         self._status_explicit: bool = False
         self._cookies: list[dict] = []
         self._headers: dict[str, str] = {}
+        self._client_ip = client_ip
+
+    @property
+    def client_ip(self) -> str | None:
+        """
+        Best-effort real caller IP — a raw signal for whatever policy the
+        PLUGIN decides (identity-aware rate limiting, audit logging,
+        fraud/abuse heuristics...). This tool never interprets it: per
+        INSTRUCTIONS_FOR_AI.md's Rate Limiting Pattern, volumetric/anonymous
+        IP throttling belongs at the edge (reverse proxy / CDN), never in
+        the monolith — but a business rule that happens to key on IP (e.g.
+        "no more than N accounts created from the same address") is exactly
+        the kind of identity-aware policy that pattern says belongs in the
+        plugin, with the `state` tool primitive. This property is what makes
+        that possible; it does not pick a policy itself.
+
+        Trust order (see pipeline.py's _extract_client_ip): Cf-Connecting-Ip,
+        then X-Forwarded-For's first hop, then the direct TCP peer. The first
+        two are only as trustworthy as whatever reverse proxy sets them —
+        this tool cannot verify one is actually in front of it. None if no
+        signal was available at all (e.g. request.client itself is None).
+        """
+        return self._client_ip
 
     def set_status(self, code: int) -> None:
         """

{microcoreos-0.3.2 → microcoreos-0.4.0}/tools/http_server/http_server_tool.py

@@ -96,6 +96,12 @@ HttpContext API:
     context.set_header(key, value)          → Add a custom response header
     context.redirect(url, status=302)       → Redirect to another URL
     context.set_binary_response(content, media_type) → Return raw binary data
+    context.client_ip                       → Best-effort caller IP (property, not a
+                                               call) — a raw signal for the PLUGIN's own
+                                               policy (identity-aware rate limiting,
+                                               audit logging...). See INSTRUCTIONS_FOR_AI.md's
+                                               Rate Limiting Pattern: this tool never
+                                               decides a policy, it only exposes the signal.
 
 
 AUTH VALIDATOR CONTRACT:
@@ -132,7 +138,9 @@ REPLACEMENT STANDARD (implement this to swap the backend):
           add_sse_endpoint(path, generator, tags, auth_validator)
     4. Handler contract: handler(data: dict, context: HttpContext) → dict
        - data: flat merge of path params + query params + body (+ _files if applicable)
-       - context: instance of HttpContext (or a compatible duck-type)
+       - context: instance of HttpContext (or a compatible duck-type), constructed with
+         client_ip= the best-effort caller IP for this backend's own request object
+         (see pipeline.py's _extract_client_ip for the header trust order to mirror)
     5. Honor context.status_code and context.binary_content for the HTTP response.
        If the handler never called context.set_status() and the result dict has
        success: False, default to HTTP 400 instead of 200 (context._status_explicit
@@ -355,6 +363,10 @@ class HttpServerTool(BaseTool):
             - context.set_cookie(key, value, max_age=3600, ...): Set secure response cookie.
             - context.set_header(key, value): Add custom response header.
             - context.set_binary_response(content: bytes, media_type: str): Return raw file.
+            - context.client_ip: Best-effort caller IP (property). Raw signal only — the
+              plugin decides what to do with it (e.g. state.increment() keyed by IP for
+              an identity-aware business rule). Never security-authoritative on its own;
+              see context.py's client_ip docstring for the trust order and its limits.
         - RESPONSE CONTRACT:
             - Standard: return {"success": bool, "data": ..., "error": ...}
             - WARNING: All values in 'data' must be JSON-serializable. Pydantic model