agentx-security-sdk 0.4.0__tar.gz → 0.4.2__tar.gz

{agentx_security_sdk-0.4.0 → agentx_security_sdk-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentx-security-sdk
-Version: 0.4.0
+Version: 0.4.2
 Summary: Runtime firewall for AI agents - blocks catastrophic tool calls and self-heals the run.
 Home-page: https://agentx-core.com
 Author: AgentX Core Team
@@ -147,6 +147,21 @@ Don't own the tool's Python? Running a non-Python agent? Wrap any **MCP server**
 
 `agentx-mcp <real server command>` spawns the real server and relays the protocol untouched, intercepting only tool calls. A blocked call comes back to the agent as a coaching tool error it can self-correct on, so the run keeps going and the dangerous call never reaches the server.
 
+**No Python in your stack?** You don't need a persistent install. Run it on demand with [`uvx`](https://docs.astral.sh/uv/) (or `pipx run`), which fetches the package into a throwaway environment, so your `mcp.json` stays one line:
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "uvx",
+      "args": ["--from", "agentx-security-sdk", "agentx-mcp", "npx", "-y", "@modelcontextprotocol/server-filesystem", "/data"]
+    }
+  }
+}
+```
+
+(`pipx run --spec agentx-security-sdk agentx-mcp <real server command>` works the same way.)
+
 ---
 
 ### Step 3: See your first block: no key, no gateway, no signup
@@ -204,7 +219,7 @@ Injected Input Payload: 'Customer requested normal update. Retain account histor
 
 ### Step 4: (Upgrade) Recover: turn hard blocks into recoverable challenges
 
-Everything above is keyless **Shield**. The **reasoning axis** (orthogonal to `AGENTX_MODE`) turns a block from a dead end into a **recoverable, task-fitting challenge** the agent self-corrects from, plus Discovery for novel-intent classification. This is **Recover**, the tier no `403`-style firewall has. It takes two things, and they go together:
+Everything above is keyless **Shield**: it blocks the blatant calls and coaches your agent to self-correct. The **reasoning axis** (orthogonal to `AGENTX_MODE`) is **Recover**: the gateway judge catches what the keyword floor can't see, writes the **task-fitting challenge** when your policy carries none, and runs the coach-and-retry for you, plus Discovery for novel-intent classification. The tier no `403`-style firewall has. It takes two things, and they go together:
 
 **1. A `GEMINI_API_KEY`**, the cheap part. Copy `.env.example` to `.env` and set it:
 
@@ -350,7 +365,7 @@ Inside the examples/ folder, you will find a few standalone scripts proving the
 * **04_circuit_breaker_demo.py:** AgentX catches and prevents an infinite apology loop, saving time and tokens.
 * **06_hitl_escalation.py:** See how an agent safely pauses execution and pings a SOC analyst for approval using a 202 Accepted queue.
 * **09_budget_ceiling_demo.py:** Watch AgentX meter a runaway agent's cumulative spend and halt the session the moment it crosses your budget ceiling, a deterministic, gateway-side escalation (no LLM judge). Needs the gateway running + a key.
-* **10_self_correction_coaching.py:** The Recover tier, a block that *coaches*. AgentX blocks a dangerous action and returns a task-fitting challenge that names a safe path, so your agent finishes the job instead of dead-ending. Puts the AgentX challenge side by side with a plain guardrail's, then watches the agent recover on it. Needs the gateway running + your Gemini key (the upgrade from the keyless Shield).
+* **10_self_correction_coaching.py:** The Recover tier, where the gateway judge does the coaching for you. AgentX blocks a dangerous action and returns a task-fitting challenge that names a safe path, so your agent finishes the job instead of dead-ending. Puts the AgentX challenge side by side with a plain guardrail's, then watches the agent recover on it. Needs the gateway running + your Gemini key (the keyless Shield already coaches in-band; Recover's judge catches more and runs the retry for you).
 * **And many more...**
 
 ---

{agentx_security_sdk-0.4.0 → agentx_security_sdk-0.4.2}/README.md

@@ -109,6 +109,21 @@ Don't own the tool's Python? Running a non-Python agent? Wrap any **MCP server**
 
 `agentx-mcp <real server command>` spawns the real server and relays the protocol untouched, intercepting only tool calls. A blocked call comes back to the agent as a coaching tool error it can self-correct on, so the run keeps going and the dangerous call never reaches the server.
 
+**No Python in your stack?** You don't need a persistent install. Run it on demand with [`uvx`](https://docs.astral.sh/uv/) (or `pipx run`), which fetches the package into a throwaway environment, so your `mcp.json` stays one line:
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "uvx",
+      "args": ["--from", "agentx-security-sdk", "agentx-mcp", "npx", "-y", "@modelcontextprotocol/server-filesystem", "/data"]
+    }
+  }
+}
+```
+
+(`pipx run --spec agentx-security-sdk agentx-mcp <real server command>` works the same way.)
+
 ---
 
 ### Step 3: See your first block: no key, no gateway, no signup
@@ -166,7 +181,7 @@ Injected Input Payload: 'Customer requested normal update. Retain account histor
 
 ### Step 4: (Upgrade) Recover: turn hard blocks into recoverable challenges
 
-Everything above is keyless **Shield**. The **reasoning axis** (orthogonal to `AGENTX_MODE`) turns a block from a dead end into a **recoverable, task-fitting challenge** the agent self-corrects from, plus Discovery for novel-intent classification. This is **Recover**, the tier no `403`-style firewall has. It takes two things, and they go together:
+Everything above is keyless **Shield**: it blocks the blatant calls and coaches your agent to self-correct. The **reasoning axis** (orthogonal to `AGENTX_MODE`) is **Recover**: the gateway judge catches what the keyword floor can't see, writes the **task-fitting challenge** when your policy carries none, and runs the coach-and-retry for you, plus Discovery for novel-intent classification. The tier no `403`-style firewall has. It takes two things, and they go together:
 
 **1. A `GEMINI_API_KEY`**, the cheap part. Copy `.env.example` to `.env` and set it:
 
@@ -312,7 +327,7 @@ Inside the examples/ folder, you will find a few standalone scripts proving the
 * **04_circuit_breaker_demo.py:** AgentX catches and prevents an infinite apology loop, saving time and tokens.
 * **06_hitl_escalation.py:** See how an agent safely pauses execution and pings a SOC analyst for approval using a 202 Accepted queue.
 * **09_budget_ceiling_demo.py:** Watch AgentX meter a runaway agent's cumulative spend and halt the session the moment it crosses your budget ceiling, a deterministic, gateway-side escalation (no LLM judge). Needs the gateway running + a key.
-* **10_self_correction_coaching.py:** The Recover tier, a block that *coaches*. AgentX blocks a dangerous action and returns a task-fitting challenge that names a safe path, so your agent finishes the job instead of dead-ending. Puts the AgentX challenge side by side with a plain guardrail's, then watches the agent recover on it. Needs the gateway running + your Gemini key (the upgrade from the keyless Shield).
+* **10_self_correction_coaching.py:** The Recover tier, where the gateway judge does the coaching for you. AgentX blocks a dangerous action and returns a task-fitting challenge that names a safe path, so your agent finishes the job instead of dead-ending. Puts the AgentX challenge side by side with a plain guardrail's, then watches the agent recover on it. Needs the gateway running + your Gemini key (the keyless Shield already coaches in-band; Recover's judge catches more and runs the retry for you).
 * **And many more...**
 
 ---

{agentx_security_sdk-0.4.0 → agentx_security_sdk-0.4.2}/agentx_sdk/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.4.0"
+__version__ = "0.4.2"
 
 from .decorators import (
     agentx_protect,

{agentx_security_sdk-0.4.0 → agentx_security_sdk-0.4.2}/agentx_sdk/cli.py

@@ -1157,8 +1157,9 @@ def execute_demo():
             print(f"      receipt:  {result.receipt_id}")
         print("      The DROP TABLE never reached your database.")
         print("\n What this shows: one decorator stops a catastrophic tool call offline.")
-        print("   That's SHIELD (keyless). The goal is RECOVER: the block becomes a coached")
-        print("   self-heal so your agent finishes the task. Two steps get you there:")
+        print("   That's SHIELD (keyless): it blocks AND coaches your agent to self-correct.")
+        print("   RECOVER (gateway + key) runs the coach-and-retry for you and catches what")
+        print("   keyword rules can't see. Two steps get you there:")
         print("=" * 75)
         print(" 1 ▶ Protect your own agent. Wrap any tool, then coach and retry on a block:")
         print("       from agentx_sdk import agentx_protect, is_block")

{agentx_security_sdk-0.4.0 → agentx_security_sdk-0.4.2}/agentx_sdk/decorators.py

@@ -807,33 +807,41 @@ LOCAL_SHIELD_WEIGHTS, LOCAL_SHIELD_MANIFEST = load_local_vector_shield_cache()
 # tool/function name or payload (see _BLOCK_CATEGORY_VOCAB + pulse.py). Off-vocab is
 # dropped, so a pulled/cloud policy without a known category simply reports nothing.
 _BUILTIN_POLICY_KEYWORDS = [
+    # socratic_prompt = the agent-facing CHALLENGE; preferred_alternative = the concrete
+    # SAFE PATH. Both are written for the caller's own model to self-correct on (the
+    # keyless MCP proxy + the offline keyword shield), so they lead with the issue and a
+    # usable next step, NOT internal taxonomy or judge-era "explain your reasoning" cruft.
     {
         "id": "11111111-1111-1111-1111-111111111101",
         "name": "Mass Destructive Intent",
         "category": "DESTRUCTIVE_ACTION",
         "blocked_intents": ["DROP TABLE", "DELETE FROM", "TRUNCATE TABLE", "DROP DATABASE"],
-        "socratic_prompt": "Policy Violation: Mass Destructive Intent. Your intent to perform a DESTRUCTIVE_WRITE is prohibited. Explain your symbolic reasoning, or revise your strategy to use a SAFE_WRITE instead.",
+        "socratic_prompt": "This is a destructive, irreversible write that drops or mass-deletes data.",
+        "preferred_alternative": "Scope the change to specific rows with a WHERE clause, take a backup or snapshot first, or use a reversible soft-delete instead of dropping the table.",
     },
     {
         "id": "11111111-1111-1111-1111-111111111103",
         "name": "Network Sandbox (SSRF)",
         "category": "NETWORK_TRAVERSAL",
         "blocked_intents": ["169.254.169.254", "localhost", "127.0.0.1", "0.0.0.0"],
-        "socratic_prompt": "Policy Violation: Network Sandbox (SSRF). Direct traversal to loopback interfaces or cloud metadata endpoints is banned. Revise your target destination.",
+        "socratic_prompt": "This target is a loopback or cloud-metadata address, a common SSRF path to internal credentials.",
+        "preferred_alternative": "Send the request to the intended external service hostname over HTTPS, not an internal IP, localhost, or 169.254.169.254.",
     },
     {
         "id": "11111111-1111-1111-1111-111111111104",
         "name": "Secrets and PII Exfiltration",
         "category": "SECRETS_LEAK",
         "blocked_intents": ["system_users", "pastebin", "SELECT email", "SELECT role"],
-        "socratic_prompt": "Policy Violation: Secrets and PII Exfiltration. This request has been blocked. Change your execution path to avoid extracting secrets or PII.",
+        "socratic_prompt": "This call reads credentials or routes data to an external paste sink, which is an exfiltration path.",
+        "preferred_alternative": "Read only the non-secret fields you actually need and keep the data inside the trusted system. Do not send it to an external paste endpoint.",
     },
     {
         "id": "11111111-1111-1111-1111-111111111102",
         "name": "Customer Privacy Shield",
         "category": "PII_EXFILTRATION",
         "blocked_intents": ["SELECT email", "SELECT phone", "SELECT address", "credit_card"],
-        "socratic_prompt": "Policy Violation: Customer Privacy Shield. Accessing raw customer PII is restricted. Adjust your query to avoid retrieving un-hashed contact coordinates.",
+        "socratic_prompt": "This query pulls raw customer PII (email, phone, address, or card data). Bulk access to unmasked PII is restricted.",
+        "preferred_alternative": "Select only the non-PII fields you need, aggregate instead of returning raw rows, or use masked or hashed columns.",
     },
 ]
 
@@ -857,7 +865,10 @@ def _note_block_category(category, stats=None):
     passes its OWN stats dict so it shares this exact vocab guard instead of
     reimplementing it (the two can't drift)."""
     target = _session_stats if stats is None else stats
-    if category in _BLOCK_CATEGORY_VOCAB:
+    # isinstance guard: a malformed pulled policy can carry a NON-string category, and
+    # `<list> in <frozenset>` raises TypeError (unhashable) — drop it rather than let it
+    # wedge the block path (incl. the agentx-mcp proxy's client routing loop).
+    if isinstance(category, str) and category in _BLOCK_CATEGORY_VOCAB:
         target["block_category"] = category
 
 def load_local_policy_keywords(seed_dir=".agentx"):
@@ -893,6 +904,9 @@ def load_local_policy_keywords(seed_dir=".agentx"):
                             "blocked_intents": p.get("blocked_intents", []),
                             "socratic_prompt": p.get("socratic_prompt")
                                 or "Policy Violation. Revise your action to comply with security policy.",
+                            # Carry the concrete safe path through if the pull supplies one, so the
+                            # keyless coaching (A1a) can surface it for pulled/cloud policies too.
+                            "preferred_alternative": p.get("preferred_alternative"),
                         })
                 if policies:
                     return policies
@@ -1359,13 +1373,17 @@ def agentx_protect(agent_id: str, extract_query_func=None, extract_cot_func=None
                         else:
                             print(f"📝 [LOCAL KEYWORD SHIELD] Offline (no API key) — using local receipt: {effective_receipt}")
 
-                        # ✅ SURGICAL FIX: Route via the delivery function
+                        # ✅ SURGICAL FIX: Route via the delivery function. Coaching mirrors the
+                        # keyless MCP path (A1a): lead with the challenge + the concrete safe path,
+                        # with no judge-era "explain your symbolic reasoning" / SAFE_WRITE taxonomy
+                        # (this OFFLINE keyword-shield path has no judge), so the two keyless surfaces
+                        # emit consistent coaching. The ONLINE/judge path below keeps its own wording.
+                        ls_safe_hint = f" Safe alternative: {ls_safe_path}" if ls_safe_path else ""
                         payload = (
                             f"🚨 [AgentX Security Block] | policy: '{policy_name}' | receipt_id: '{effective_receipt}' | "
-                            f"Challenge/Constraint: {challenge_text} Explain your symbolic reasoning for this action, or revise your strategy to use a SAFE_WRITE instead. "
-                            f"System Instruction: Your request has been blocked. Analyze this security barrier, "
-                            f"adjust your parameters payload to be safe, change your execution query path, "
-                            f"and retry your tool execution turn immediately."
+                            f"Challenge/Constraint: {challenge_text}{ls_safe_hint} "
+                            f"System Instruction: Your request has been blocked. Revise the action to a "
+                            f"safe form and retry your tool execution turn immediately."
                         )
                         return _deliver_challenge(
                             payload, effective_receipt, policy_name,

{agentx_security_sdk-0.4.0 → agentx_security_sdk-0.4.2}/agentx_sdk/mcp_proxy.py

@@ -42,6 +42,7 @@ Known limitations (deliberate for v1):
     block responses. That is correct (a stalled host stalls the proxy) but head-of-line.
 """
 import json
+import os
 import subprocess
 import sys
 import threading
@@ -58,6 +59,8 @@ _real_stdout = sys.stdout
 sys.stdout = sys.stderr
 try:
     from agentx_sdk.decorators import (
+        _BLOCK_CATEGORY_VOCAB,
+        _apply_org_override,
         _coerce_arg_value,
         _max_cognitive_turns,
         _note_block_category,
@@ -98,22 +101,29 @@ def _flatten_call(name, arguments):
     return " ".join(parts)
 
 
-def _coaching_text(decision, tripped):
-    """The agent-facing block message. The policy's own challenge already names the
-    violation, so we do NOT repeat the policy name here (it stays in the stderr log
-    via _screen_message). No em dashes (house style); this text can end up in a
-    shared block card."""
+def _coaching_text(decision, tripped, tool_name=None):
+    """The agent-facing block message. Written for the CALLER'S own model to self-correct
+    on (no judge ever reads this), so it leads with the issue and the safe next step and
+    stays call-specific: it names the tool that was blocked and, when the policy carries
+    one, the concrete safe alternative (challenge-quality lever: task-fitting > generic).
+    No em dashes (house style); this text can end up in a shared block card."""
     challenge = decision.get("challenge_text") or "Revise the action to comply with security policy."
+    if challenge and challenge.rstrip()[-1:] not in ".!?":
+        challenge = challenge.rstrip() + "."   # pulled-policy text may lack end punctuation; avoid a run-on
+    safe = decision.get("preferred_alternative")
+    on_tool = " on '%s'" % tool_name if tool_name else ""
+    safe_hint = " Safe alternative: %s" % safe if safe else ""
     if tripped:
         return (
-            "AgentX circuit breaker. This call was blocked repeatedly and has been "
-            "halted to stop a runaway loop. Do not retry the same action. Choose a "
-            "safe alternative or ask the human operator. %s" % challenge
+            "AgentX circuit breaker: this call%s was blocked repeatedly and has been "
+            "halted to stop a runaway loop. Do not retry the same action. %s%s "
+            "If you cannot reach the goal safely, ask the human operator."
+            % (on_tool, challenge, safe_hint)
         )
     return (
-        "AgentX blocked this call before it ran. %s Revise the action to a safe form "
-        "and try again, or ask the human operator if you cannot reach the goal safely."
-        % challenge
+        "AgentX blocked this call%s before it ran. %s%s Revise to a safe form and try "
+        "again, or ask the human operator if you cannot reach the goal safely."
+        % (on_tool, challenge, safe_hint)
     )
 
 
@@ -127,6 +137,81 @@ def _block_response(req_id, text):
     }
 
 
+def _harvest_enabled():
+    """(B) recovery-pair harvest is OPT-IN: OFF unless AGENTX_MCP_HARVEST is truthy, so a
+    default / cold install captures NOTHING."""
+    return os.environ.get("AGENTX_MCP_HARVEST", "").strip().lower() in ("1", "true", "yes", "on")
+
+
+class _Harvest:
+    """Opt-in, tenant-private, LOCAL-ONLY capture of keyless recovery pairs
+    (designs/mcp-corpus-intake.md (B) — the SAFE-DEFAULT skeleton).
+
+    On a block it remembers ONLY {tool, policy_category}: policy_category is the closed pulse
+    vocab (validated), and tool is the SERVER-DEFINED tool identifier (NOT a vetted enum, so it
+    is kept LOCAL and never transmitted). It NEVER stores raw args / query / chain-of-thought.
+    On a later clean call to the SAME tool it forms a recovery-pair candidate, written at
+    session end to a LOCAL tenant-private file that NEVER crosses the network.
+
+    FOUNDER RATIFICATION (deliberately NOT decided here): (1) the abstraction — category+tool
+    only today; whether to capture a richer structural signature of the recovered call, AND how
+    to sanitize the server-defined tool name (raw / hashed / dropped) before any network sink,
+    is design-doc open decision #2; (2) there is NO network sink and no Discovery/adopt-queue
+    integration (moat-collection-day0, founder-gated)."""
+
+    def __init__(self):
+        self._pending = {}     # tool -> coarse policy_category (abstract only)
+        self.pairs = []        # recovery-pair candidates: {tool, policy_category, recovered}
+
+    def note_block(self, tool, category):
+        # Record ONLY a coarse category in the closed pulse vocab. An off-vocab OR non-string
+        # category (a malformed pulled policy) is dropped AND clears any stale pending entry,
+        # so a later recovery is never mis-attributed to a prior category, and a non-string
+        # category can't raise on the `in` test.
+        if isinstance(category, str) and category in _BLOCK_CATEGORY_VOCAB:
+            self._pending[tool] = category
+        else:
+            self._pending.pop(tool, None)
+
+    def note_recovery(self, tool):
+        category = self._pending.pop(tool, None)
+        if category:
+            self.pairs.append({"tool": tool, "policy_category": category, "recovered": True})
+
+
+def _harvest_path():
+    """Where the local recovery-pair file lives. An explicit AGENTX_MCP_HARVEST_PATH wins (the
+    opt-in user controls it — RECOMMENDED for MCP hosts, which launch the proxy from an unrelated
+    cwd, often $HOME or /); otherwise it sits in .agentx/ under the project root, beside the
+    overrides store. NB: launched outside a project (no .git/.agentx) the root falls back to cwd,
+    so the explicit path is preferred in the MCP execution context."""
+    explicit = os.environ.get("AGENTX_MCP_HARVEST_PATH")
+    if explicit:
+        return explicit
+    from agentx_sdk.overrides import _find_project_root
+    return os.path.join(_find_project_root(), ".agentx", "mcp_harvest.jsonl")
+
+
+def _flush_harvest(harvest, log):
+    """Append the session's recovery-pair candidates to a LOCAL tenant-private JSONL (see
+    _harvest_path). LOCAL ONLY — it never crosses the network. The record is exactly the abstract
+    pair {tool, policy_category, recovered} (NO wall-clock timestamp, which would be deanonymizing
+    once a sink ships). Best-effort: any error is swallowed so harvest can never affect the proxy
+    or the run."""
+    if not harvest or not harvest.pairs:
+        return
+    try:
+        path = _harvest_path()
+        os.makedirs(os.path.dirname(path) or ".", exist_ok=True)
+        with open(path, "a", encoding="utf-8") as f:
+            for pair in harvest.pairs:
+                f.write(json.dumps(pair) + "\n")
+        print("[agentx-mcp] harvested %d local recovery-pair candidate(s) -> %s"
+              % (len(harvest.pairs), path), file=log)
+    except Exception as err:
+        print("[agentx-mcp] harvest flush skipped: %s" % err, file=log)
+
+
 class _ClientWriter:
     """Serializes every write to the client's stdout (the sacred JSON-RPC channel).
 
@@ -176,7 +261,7 @@ def _forward(line, child_in):
     child_in.flush()
 
 
-def _screen_message(msg, session_stats, streaks, max_turns, writer, log):
+def _screen_message(msg, session_stats, streaks, max_turns, writer, log, harvest=None):
     """Screen ONE parsed JSON-RPC message. Returns ``"forward"`` (the caller relays it
     to the server) or ``"block"`` (a blocked tools/call, already handled — do NOT
     forward). Side effects on a block: emit the isError response (only if the call had
@@ -196,7 +281,19 @@ def _screen_message(msg, session_stats, streaks, max_turns, writer, log):
 
     tool_key = str(name)
     if not decision:
-        streaks.pop(tool_key, None)          # a clean call zeroes this tool's block streak
+        # A clean call zeroes this tool's block streak. If that streak was non-zero, this
+        # SAME tool was blocked earlier and now runs safe: a rough proxy for "the agent
+        # recovered on the coaching", so count it on the pulse. This is a HEURISTIC keyed
+        # by tool name (the keyless proxy has no per-call trace) so it can over-attribute
+        # (a later unrelated clean call on a tool that was once blocked) and under-count
+        # cross-tool recoveries; it is therefore NOT identical to the decorator's
+        # trace-keyed _credit_recovery (which bounds recovered <= challenged). Counts-only
+        # / advisory: harvest-IN (designs/mcp-corpus-intake.md (B))'s block->allow
+        # correlation hook used purely to COUNT (capturing the revised-safe call is later).
+        if streaks.pop(tool_key, None):
+            session_stats["self_corrections"] = session_stats.get("self_corrections", 0) + 1
+            if harvest is not None:
+                harvest.note_recovery(tool_key)   # (B): form the abstract recovery-pair
         return "forward"
 
     # Blocked. Match the decorator's breaker edge: _trip_breaker_if_ceiling checks the
@@ -215,7 +312,22 @@ def _screen_message(msg, session_stats, streaks, max_turns, writer, log):
 
     req_id = msg.get("id")
     if req_id is not None:
-        writer.send(_block_response(req_id, _coaching_text(decision, tripped)))
+        if harvest is not None:
+            # (B): only a block that was actually COACHED (had an id to answer) is a harvest
+            # candidate — an id-less blocked call is dropped with no coaching, so a later clean
+            # call on it is not a coached recovery.
+            harvest.note_block(tool_key, decision.get("category"))
+        # A1b: enrich the keyless coaching with the org's adopted reframe (challenge +
+        # safe-path) via the SHARED _apply_org_override the decorator uses, so the org
+        # brain reaches the MCP wedge too and the two keyless paths can't drift. Keyless:
+        # it reads the local .agentx/overrides.json (no gateway). Total best-effort — it
+        # returns the inputs unchanged when nothing is adopted, so the cold install (the
+        # funnel target, no overrides) is completely unaffected.
+        ch, safe = _apply_org_override(
+            decision.get("policy_id"), decision.get("challenge_text"),
+            decision.get("preferred_alternative"), policy_name=decision.get("policy_name"))
+        coached = dict(decision, challenge_text=ch, preferred_alternative=safe)
+        writer.send(_block_response(req_id, _coaching_text(coached, tripped, name)))
     else:
         # A tools/call shaped as a notification (no id) cannot be answered, but it must
         # NOT be forwarded either — drop it so the dangerous call never reaches the server.
@@ -226,7 +338,7 @@ def _screen_message(msg, session_stats, streaks, max_turns, writer, log):
     return "block"
 
 
-def _route_line(line, child_in, writer, session_stats, streaks, max_turns, log):
+def _route_line(line, child_in, writer, session_stats, streaks, max_turns, log, harvest=None):
     """Handle ONE client->server line. Forwards it to the child UNLESS a tools/call in
     it is blocked by the keyless shield. Scalars are forwarded byte-for-byte; a batch
     (JSON array) is screened member by member and only the un-blocked members are
@@ -246,13 +358,13 @@ def _route_line(line, child_in, writer, session_stats, streaks, max_turns, log):
     # dangerous tools/call buried in a batch can't slip through unscreened.
     if isinstance(msg, list):
         keep = [item for item in msg
-                if _screen_message(item, session_stats, streaks, max_turns, writer, log) == "forward"]
+                if _screen_message(item, session_stats, streaks, max_turns, writer, log, harvest) == "forward"]
         if keep:
             child_in.write(json.dumps(keep) + "\n")
             child_in.flush()
         return
 
-    if _screen_message(msg, session_stats, streaks, max_turns, writer, log) == "forward":
+    if _screen_message(msg, session_stats, streaks, max_turns, writer, log, harvest) == "forward":
         _forward(line, child_in)             # scalar: forward the ORIGINAL line verbatim
 
 
@@ -269,6 +381,7 @@ def run_proxy(child_cmd, *, client_in, client_out, session_stats, log=None,
     log = log or sys.stderr
     max_turns = _max_cognitive_turns()
     streaks = {}
+    harvest = _Harvest() if _harvest_enabled() else None   # (B): opt-in, default OFF -> inert
     writer = _ClientWriter(client_out)
 
     def _default_popen(cmd):
@@ -313,7 +426,7 @@ def run_proxy(child_cmd, *, client_in, client_out, session_stats, log=None,
 
     try:
         for line in client_in:
-            _route_line(line, child.stdin, writer, session_stats, streaks, max_turns, log)
+            _route_line(line, child.stdin, writer, session_stats, streaks, max_turns, log, harvest)
     except Exception as err:
         print("[agentx-mcp] client stream error: %s" % err, file=log)
     finally:
@@ -321,6 +434,7 @@ def run_proxy(child_cmd, *, client_in, client_out, session_stats, log=None,
             child.stdin.close()
         except Exception:
             pass
+        _flush_harvest(harvest, log)   # (B): write the session's local, abstract recovery pairs
 
     try:
         rc = child.wait(timeout=10)
@@ -380,7 +494,7 @@ def main(argv=None):
     decorators.suppress_atexit_summary()
 
     session_stats = {"integration": "mcp", "total_calls": 0,
-                     "intercepts": 0, "critical_blocks": 0}
+                     "intercepts": 0, "critical_blocks": 0, "self_corrections": 0}
 
     def _emit_pulse():
         # Mirror the decorator path (decorators.py): never emit a pulse from CI /

{agentx_security_sdk-0.4.0 → agentx_security_sdk-0.4.2}/agentx_sdk/pulse.py

@@ -354,9 +354,11 @@ def maybe_emit_nudge(session_stats):
         now = time.time()
         if _should_emit_nudge(session_stats, state, now):
             print("─" * 60)
-            print(" ▶ That was the keyless Shield (block only). Recover makes your agent")
-            print("   heal and finish the task instead of dead-ending on the block.")
-            print("   Unlock it: agentx-core.com/#request-access")
+            print(" ▶ That was the keyless Shield: it blocked the call AND coached your")
+            print("   agent to self-correct. Recover (gateway + key)")
+            print("   adds the judge that catches what keywords miss, auto-runs the retry,")
+            print("   and escalates the biggest calls to a human.")
+            print("   Unlock Recover: agentx-core.com/#request-access")
             print("   Community: discord.gg/PmWRTtaSx2")
             state["last_nudge_ts"] = now
             changed = True

{agentx_security_sdk-0.4.0 → agentx_security_sdk-0.4.2}/agentx_sdk/test_agentx_sdk.py

@@ -388,6 +388,30 @@ def test_layer0_still_blocks_destructive_catalog_op_when_intent_armed(monkeypatc
     assert "🚨 [AgentX Security Block]" in str(result)
 
 
+def test_offline_keyword_shield_coaching_is_decrufted_and_names_safe_path(monkeypatch):
+    """The offline keyword-shield block coaching mirrors the keyless MCP path (A1a): no
+    judge-era 'symbolic reasoning' / SAFE_WRITE taxonomy (this path has no judge), and it
+    surfaces the policy's concrete safe path, so the two keyless surfaces stay consistent."""
+    import agentx_sdk.decorators as dec
+
+    armed = [{
+        "id": "11111111-1111-1111-1111-111111111105",
+        "name": "Schema Boundary",
+        "blocked_intents": ["drop schema", "alter database"],
+        "socratic_prompt": "This drops or alters catalog schema, which is restricted.",
+        "preferred_alternative": "Target only your own tables, or use a read-only catalog query.",
+    }]
+    monkeypatch.setattr(dec, "LOCAL_POLICY_KEYWORDS", armed)
+    monkeypatch.delenv("AGENTX_BYPASS_LOCAL_SHIELD", raising=False)
+
+    result = str(mock_secure_database_executor(sql_query="DROP SCHEMA public"))
+    assert "🚨 [AgentX Security Block]" in result
+    assert "symbolic reasoning" not in result.lower()     # judge-era cruft removed
+    assert "SAFE_WRITE" not in result                      # internal taxonomy removed
+    assert "Safe alternative:" in result                   # surfaces preferred_alternative
+    assert "read-only catalog query" in result             # the concrete safe path
+
+
 def test_is_fs_destructive_func_tokenizes_name():
     """Verb is matched as a discrete token (snake_case + camelCase), never as a
     substring — so `undelete_safely` / `formatter` do not false-positive."""

{agentx_security_sdk-0.4.0 → agentx_security_sdk-0.4.2}/agentx_sdk/test_mcp_proxy.py

@@ -32,13 +32,13 @@ def _line(method="tools/call", *, id=1, name="run_sql", arguments=None, **extra)
     return json.dumps(msg) + "\n"
 
 
-def _route(line, *, stats=None, streaks=None, max_turns=3):
+def _route(line, *, stats=None, streaks=None, max_turns=3, harvest=None):
     """Drive one line through the core with in-memory streams. Returns
     (forwarded_to_child, sent_to_client, stats)."""
     child, client = io.StringIO(), io.StringIO()
     stats = {} if stats is None else stats
     mp._route_line(line, child, mp._ClientWriter(client), stats,
-                   {} if streaks is None else streaks, max_turns, io.StringIO())
+                   {} if streaks is None else streaks, max_turns, io.StringIO(), harvest)
     return child.getvalue(), client.getvalue(), stats
 
 
@@ -125,6 +125,21 @@ def test_block_category_off_vocab_is_not_emitted(monkeypatch):
     assert "block_category" not in stats           # off-vocab dropped, never emitted
 
 
+def test_non_string_category_does_not_wedge_screening(monkeypatch):
+    """A malformed pulled policy can carry a NON-string category; screening must drop it
+    without raising (a TypeError in `<list> in <frozenset>` would wedge the whole client
+    routing loop). Pre-existing base-path fragility surfaced by the #135 review."""
+    decision = {"policy_name": "X", "challenge_text": "no", "category": ["weird", "list"],
+                "policy_id": "P", "preferred_alternative": None}
+    monkeypatch.setattr(mp, "evaluate_call_keyless", lambda q: decision)
+    stats = {}
+    mp._screen_message({"jsonrpc": "2.0", "id": 1, "method": "tools/call",
+                        "params": {"name": "t", "arguments": {}}},
+                       stats, {}, 3, mp._ClientWriter(io.StringIO()), io.StringIO())
+    assert "block_category" not in stats           # non-string category dropped, never emitted
+    assert stats["critical_blocks"] == 1           # the block still stood; the loop did not wedge
+
+
 def test_benign_catalog_read_is_exempt():
     line = _line(id=3, name="run_sql",
                  arguments={"query": "SELECT * FROM information_schema.columns"})
@@ -155,6 +170,163 @@ def test_allow_resets_block_streak():
     assert "run_sql" not in streaks             # a clean call zeroes the streak
 
 
+# --------------------------------------------------------------------------- #
+# A1a — coaching is call-fitting and names a safe path (not generic)
+# --------------------------------------------------------------------------- #
+def test_block_coaching_is_call_fitting_and_names_a_safe_path(monkeypatch):
+    """The keyless coaching names the blocked TOOL and the policy's concrete safe
+    alternative, so the caller's model gets a task-fitting hint to recover on (not a
+    generic 'policy violation'), and the judge-era cruft is gone. Arm the shipped
+    builtins explicitly: a dev machine may carry a pulled .agentx/policies.json that
+    shadows them, but the cold/keyless install (the funnel target) runs the builtins."""
+    from agentx_sdk import decorators as dec
+    monkeypatch.setattr(dec, "LOCAL_POLICY_KEYWORDS", list(dec._BUILTIN_POLICY_KEYWORDS))
+    line = _line(name="run_sql", arguments={"query": "DROP TABLE users;"})
+    _, client_out, _ = _route(line)
+    text = json.loads(client_out)["result"]["content"][0]["text"]
+    assert "run_sql" in text                       # call-fitting: names the blocked tool
+    assert "Safe alternative:" in text             # surfaces preferred_alternative
+    assert "WHERE clause" in text                  # the concrete safe path, not boilerplate
+    assert "symbolic reasoning" not in text.lower()   # judge-era cruft removed
+
+
+# --------------------------------------------------------------------------- #
+# A2 — the proxy counts a keyless recover (same-tool block -> later allow)
+# --------------------------------------------------------------------------- #
+def test_same_tool_block_then_allow_counts_a_self_correction():
+    """The proxy is the only place that sees BOTH halves of a recovery. A block on tool
+    T followed by a clean call on T (the model's safe revision) increments
+    self_corrections, making the keyless recover visible on the pulse. Conservative:
+    only a clean SAME-tool block->allow counts."""
+    danger = _line(name="run_sql", arguments={"query": "DROP TABLE users;"})
+    safe = _line(name="run_sql", arguments={"query": "SELECT 1"})
+    stats, streaks = {}, {}
+    _route(danger, stats=stats, streaks=streaks)
+    assert stats.get("self_corrections", 0) == 0   # a block alone is not a recovery
+    _route(safe, stats=stats, streaks=streaks)
+    assert stats["self_corrections"] == 1          # same tool now runs safe -> recovered
+
+
+def test_clean_call_without_prior_block_is_not_a_self_correction():
+    """A clean call on a tool that was never blocked must NOT count as a recovery."""
+    _, _, stats = _route(_line(name="read_file", arguments={"path": "/data/ok.txt"}))
+    assert stats.get("self_corrections", 0) == 0   # no prior block -> no over-count
+
+
+# --------------------------------------------------------------------------- #
+# (B) harvest-IN — opt-in, abstract-only, local recovery-pair capture
+# --------------------------------------------------------------------------- #
+def test_harvest_is_opt_in_off_by_default(monkeypatch):
+    monkeypatch.delenv("AGENTX_MCP_HARVEST", raising=False)
+    assert mp._harvest_enabled() is False
+    monkeypatch.setenv("AGENTX_MCP_HARVEST", "1")
+    assert mp._harvest_enabled() is True
+
+
+def test_harvest_records_abstract_recovery_pair():
+    """A same-tool block->allow yields ONE recovery-pair candidate carrying only the coarse
+    {tool, policy_category} — never a raw payload."""
+    h = mp._Harvest()
+    stats, streaks = {}, {}
+    _route(_line(name="run_sql", arguments={"query": "DROP TABLE users;"}),
+           stats=stats, streaks=streaks, harvest=h)
+    assert h.pairs == []                                    # a block alone is not a pair
+    _route(_line(name="run_sql", arguments={"query": "SELECT 1"}),
+           stats=stats, streaks=streaks, harvest=h)
+    assert h.pairs == [{"tool": "run_sql", "policy_category": "DESTRUCTIVE_ACTION", "recovered": True}]
+    assert "DROP TABLE" not in json.dumps(h.pairs)         # privacy: no raw payload captured
+
+
+def test_harvest_drops_off_vocab_category():
+    """A category outside the closed pulse vocab is never captured (privacy guard)."""
+    h = mp._Harvest()
+    h.note_block("t", "internal-billing-rule")             # off-vocab -> dropped
+    h.note_recovery("t")
+    assert h.pairs == []
+
+
+def test_flush_harvest_writes_exact_abstract_pair_to_local_jsonl(tmp_path, monkeypatch):
+    """Flush appends the EXACT abstract pair (no deanonymizing timestamp) to a LOCAL jsonl
+    under the project root, best-effort."""
+    monkeypatch.delenv("AGENTX_MCP_HARVEST_PATH", raising=False)
+    monkeypatch.setattr("agentx_sdk.overrides._find_project_root", lambda *a, **k: str(tmp_path))
+    h = mp._Harvest()
+    h.pairs = [{"tool": "run_sql", "policy_category": "DESTRUCTIVE_ACTION", "recovered": True}]
+    mp._flush_harvest(h, io.StringIO())
+    out = tmp_path / ".agentx" / "mcp_harvest.jsonl"
+    assert out.exists()
+    rec = json.loads(out.read_text(encoding="utf-8").strip())
+    assert rec == {"tool": "run_sql", "policy_category": "DESTRUCTIVE_ACTION", "recovered": True}
+
+
+def test_flush_harvest_honors_explicit_path(tmp_path, monkeypatch):
+    """An explicit AGENTX_MCP_HARVEST_PATH wins (the MCP-context control)."""
+    target = tmp_path / "nested" / "harvest.jsonl"
+    monkeypatch.setenv("AGENTX_MCP_HARVEST_PATH", str(target))
+    h = mp._Harvest()
+    h.pairs = [{"tool": "t", "policy_category": "SECRETS_LEAK", "recovered": True}]
+    mp._flush_harvest(h, io.StringIO())
+    assert target.exists()
+
+
+def test_harvest_off_vocab_block_clears_stale_pending():
+    """An off-vocab re-block clears a stale pending category, so a later recovery is not
+    mis-attributed to the earlier category (or crashed by a non-string category)."""
+    h = mp._Harvest()
+    h.note_block("t", "DESTRUCTIVE_ACTION")        # in-vocab -> pending
+    h.note_block("t", "internal-billing-rule")     # off-vocab -> CLEARS pending
+    h.note_block("u", ["weird", "list"])           # non-string -> dropped, no crash
+    h.note_recovery("t")
+    assert h.pairs == []                            # no mis-attributed pair
+
+
+def test_harvest_skips_idless_uncoached_block():
+    """An id-less blocked call is dropped with no coaching, so a later clean call on that tool
+    is NOT recorded as a coached recovery (no phantom pair)."""
+    h = mp._Harvest()
+    stats, streaks = {}, {}
+    _route(_line(id=None, name="run_sql", arguments={"query": "DROP TABLE users;"}),
+           stats=stats, streaks=streaks, harvest=h)   # id-less block: dropped, not harvested
+    _route(_line(name="run_sql", arguments={"query": "SELECT 1"}),
+           stats=stats, streaks=streaks, harvest=h)
+    assert h.pairs == []                              # no phantom pair from an uncoached block
+
+
+# --------------------------------------------------------------------------- #
+# A1b — the org's adopted reframe reaches the keyless MCP coaching
+# --------------------------------------------------------------------------- #
+def test_org_reframe_is_injected_into_keyless_coaching(monkeypatch):
+    """When the org has adopted a reframe for the blocked policy, the keyless MCP coaching
+    carries the adopted challenge + safe-path (via the SHARED _apply_org_override the
+    decorator uses), so the org brain reaches the MCP wedge. Reads only the local
+    overrides store (keyless, no gateway)."""
+    from agentx_sdk import decorators as dec
+    reframe = {"challenge": "Use the audited soft_delete procedure for this table.",
+               "safe_path": "Call soft_delete(table, where=...) instead of DROP."}
+    monkeypatch.setattr(dec, "get_active_override",
+                        lambda policy_id, policy_name=None, **k: reframe)
+
+    line = _line(name="run_sql", arguments={"query": "DROP TABLE users;"})
+    _, client_out, _ = _route(line)
+    text = json.loads(client_out)["result"]["content"][0]["text"]
+    assert "audited soft_delete procedure" in text          # adopted challenge swapped in
+    assert "Safe alternative:" in text                      # adopted safe-path surfaced
+    assert "soft_delete(table" in text
+
+
+def test_no_org_override_leaves_base_coaching_unchanged(monkeypatch):
+    """No adopted override -> the base builtin coaching is delivered unchanged, so the
+    cold install (the funnel target, no overrides) is unaffected by A1b."""
+    from agentx_sdk import decorators as dec
+    monkeypatch.setattr(dec, "get_active_override", lambda *a, **k: None)
+
+    line = _line(name="run_sql", arguments={"query": "DROP TABLE users;"})
+    _, client_out, _ = _route(line)
+    text = json.loads(client_out)["result"]["content"][0]["text"]
+    assert "AgentX blocked this call" in text               # base wrapper, no reframe
+    assert "soft_delete" not in text
+
+
 # --------------------------------------------------------------------------- #
 # flatten
 # --------------------------------------------------------------------------- #

{agentx_security_sdk-0.4.0 → agentx_security_sdk-0.4.2}/agentx_security_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentx-security-sdk
-Version: 0.4.0
+Version: 0.4.2
 Summary: Runtime firewall for AI agents - blocks catastrophic tool calls and self-heals the run.
 Home-page: https://agentx-core.com
 Author: AgentX Core Team
@@ -147,6 +147,21 @@ Don't own the tool's Python? Running a non-Python agent? Wrap any **MCP server**
 
 `agentx-mcp <real server command>` spawns the real server and relays the protocol untouched, intercepting only tool calls. A blocked call comes back to the agent as a coaching tool error it can self-correct on, so the run keeps going and the dangerous call never reaches the server.
 
+**No Python in your stack?** You don't need a persistent install. Run it on demand with [`uvx`](https://docs.astral.sh/uv/) (or `pipx run`), which fetches the package into a throwaway environment, so your `mcp.json` stays one line:
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "uvx",
+      "args": ["--from", "agentx-security-sdk", "agentx-mcp", "npx", "-y", "@modelcontextprotocol/server-filesystem", "/data"]
+    }
+  }
+}
+```
+
+(`pipx run --spec agentx-security-sdk agentx-mcp <real server command>` works the same way.)
+
 ---
 
 ### Step 3: See your first block: no key, no gateway, no signup
@@ -204,7 +219,7 @@ Injected Input Payload: 'Customer requested normal update. Retain account histor
 
 ### Step 4: (Upgrade) Recover: turn hard blocks into recoverable challenges
 
-Everything above is keyless **Shield**. The **reasoning axis** (orthogonal to `AGENTX_MODE`) turns a block from a dead end into a **recoverable, task-fitting challenge** the agent self-corrects from, plus Discovery for novel-intent classification. This is **Recover**, the tier no `403`-style firewall has. It takes two things, and they go together:
+Everything above is keyless **Shield**: it blocks the blatant calls and coaches your agent to self-correct. The **reasoning axis** (orthogonal to `AGENTX_MODE`) is **Recover**: the gateway judge catches what the keyword floor can't see, writes the **task-fitting challenge** when your policy carries none, and runs the coach-and-retry for you, plus Discovery for novel-intent classification. The tier no `403`-style firewall has. It takes two things, and they go together:
 
 **1. A `GEMINI_API_KEY`**, the cheap part. Copy `.env.example` to `.env` and set it:
 
@@ -350,7 +365,7 @@ Inside the examples/ folder, you will find a few standalone scripts proving the
 * **04_circuit_breaker_demo.py:** AgentX catches and prevents an infinite apology loop, saving time and tokens.
 * **06_hitl_escalation.py:** See how an agent safely pauses execution and pings a SOC analyst for approval using a 202 Accepted queue.
 * **09_budget_ceiling_demo.py:** Watch AgentX meter a runaway agent's cumulative spend and halt the session the moment it crosses your budget ceiling, a deterministic, gateway-side escalation (no LLM judge). Needs the gateway running + a key.
-* **10_self_correction_coaching.py:** The Recover tier, a block that *coaches*. AgentX blocks a dangerous action and returns a task-fitting challenge that names a safe path, so your agent finishes the job instead of dead-ending. Puts the AgentX challenge side by side with a plain guardrail's, then watches the agent recover on it. Needs the gateway running + your Gemini key (the upgrade from the keyless Shield).
+* **10_self_correction_coaching.py:** The Recover tier, where the gateway judge does the coaching for you. AgentX blocks a dangerous action and returns a task-fitting challenge that names a safe path, so your agent finishes the job instead of dead-ending. Puts the AgentX challenge side by side with a plain guardrail's, then watches the agent recover on it. Needs the gateway running + your Gemini key (the keyless Shield already coaches in-band; Recover's judge catches more and runs the retry for you).
 * **And many more...**
 
 ---

{agentx_security_sdk-0.4.0 → agentx_security_sdk-0.4.2}/setup.py

@@ -9,7 +9,7 @@ if os.path.exists("README.md"):
 
 setup(
     name="agentx-security-sdk",
-    version="0.4.0",
+    version="0.4.2",
     author="AgentX Core Team",
     author_email="founders@agentx-core.com",
     description="Runtime firewall for AI agents - blocks catastrophic tool calls and self-heals the run.",