agentctrl 0.2.1__tar.gz → 0.2.2__tar.gz

agentctrl-0.2.2/.gitignore

@@ -0,0 +1,76 @@
+# ── Python ───────────────────────────────────────────
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+dist/
+build/
+.eggs/
+*.so
+
+# Virtual environments
+.venv/
+backend/.venv/
+venv/
+env/
+
+# ── Node / Next.js ────────────────────────────────────
+node_modules/
+frontend/node_modules/
+frontend/.next/
+frontend/.next.trash/
+frontend/out/
+frontend/.vercel/
+.npm
+
+# ── Environment & Secrets ─────────────────────────────
+.env
+.env.local
+.env.production
+.env.*.local
+# Keep .env.example (it's safe to share)
+!.env.example
+# Integration credentials saved via in-platform UI (contains API keys)
+integrations.json
+
+# ── Databases & Storage ───────────────────────────────
+*.db
+*.sqlite
+*.sqlite3
+postgres-data/
+redis-data/
+
+# ── IDE & OS ──────────────────────────────────────────
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+.idea/
+.vscode/
+.cursor/plans/
+.cursor/debug-*.log
+*.swp
+*.swo
+
+# ── Logs ──────────────────────────────────────────────
+*.log
+logs/
+npm-debug.log*
+yarn-debug.log*
+
+# ── Docker ────────────────────────────────────────────
+.docker/
+
+# ── Test/Build Caches ─────────────────────────────────
+.pytest_cache/
+.ruff_cache/
+
+# ── Misc ──────────────────────────────────────────────
+*.bak
+*.tmp
+.cache/

{agentctrl-0.2.1 → agentctrl-0.2.2}/CHANGELOG.md

@@ -6,6 +6,19 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pr
 
 ---
 
+## [0.2.2] — 2026-04-12
+
+### Added
+- **Advisory context on early exit.** When a pipeline stage short-circuits with ESCALATE or BLOCK, remaining stages (risk, conflict) still run as `ADVISORY` — their results are appended to the decision record for reviewer visibility but do not change the decision.
+- New `ADVISORY` status for `PipelineStageResult` (non-decision, informational).
+- 3 new tests: `test_advisory_context_on_autonomy_escalate`, `test_advisory_context_on_early_exit`, `test_allow_has_no_advisory_stages`.
+
+### Changed
+- `_run_pipeline()` early-exit paths now call `_collect_advisory_context()` instead of returning immediately.
+- Test count updated to 8 (was 5 before advisory context tests).
+
+---
+
 ## [0.2.1] — 2026-04-11
 
 ### Added

{agentctrl-0.2.1 → agentctrl-0.2.2}/CONTRIBUTING.md

@@ -33,7 +33,7 @@ This installs the library in editable mode with all optional dependencies (netwo
 python -m pytest tests/ -v
 ```
 
-All 76 tests should pass. No external services required — everything runs in-process.
+79 tests total (78 pass, 1 skipped). No external services required — everything runs in-process.
 
 ---
 

{agentctrl-0.2.1 → agentctrl-0.2.2}/PKG-INFO

@@ -1,13 +1,12 @@
 Metadata-Version: 2.4
 Name: agentctrl
-Version: 0.2.1
+Version: 0.2.2
 Summary: Institutional control layer for AI agent actions — authority, policy, risk, and audit before execution.
 Project-URL: Homepage, https://moeintel.ai
 Project-URL: Repository, https://github.com/moeintel/AgentCTRL
 Project-URL: Issues, https://github.com/moeintel/AgentCTRL/issues
 Author: MoeIntel
 License-Expression: Apache-2.0
-License-File: LICENSE
 Keywords: ai-agents,authority,crewai,governance,langchain,openai,policy-engine,risk-scoring
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
@@ -117,7 +116,7 @@ Those are institutional controls. They existed for human employees. They need to
 - **Fail-closed.** Any pipeline error produces BLOCK, never silent approval.
 - **Structural enforcement.** Policies are operator-based rule matching, not prompt instructions. Authority is graph traversal. Risk is weighted factor scoring. None of this is prompt engineering.
 
-> **Status:** 76 tests passing. Published on [PyPI](https://pypi.org/project/agentctrl/).
+> **Status:** 79 tests passing. Published on [PyPI](https://pypi.org/project/agentctrl/).
 
 ---
 
@@ -334,7 +333,7 @@ agent = Agent(role="analyst", tools=[governed_tool])
 
 ## Decision Pipeline
 
-Every action passes through 5 stages in order. Each can short-circuit.
+Every action passes through 5 stages in order. Each can short-circuit with BLOCK or ESCALATE. When a stage short-circuits, remaining stages still run as **ADVISORY** — their results are appended to the decision record for reviewer visibility but do not change the decision.
 
 ```
 Agent proposes action
@@ -346,6 +345,7 @@ Agent proposes action
     → Risk Scoring (how risky is this action in context?)
     → Conflict Detection (does this clash with other active workflows?)
     → Decision: ALLOW / ESCALATE / BLOCK
+         (+ ADVISORY stages from remaining pipeline on early exit)
 ```
 
 ### Policy Engine
@@ -441,7 +441,7 @@ result = await gateway.validate(proposal)
 python -m pytest tests/ -v
 ```
 
-76 tests covering: pipeline stages, fail-closed behavior, policy evaluation (AND/OR groups, 14 operators, temporal conditions), authority graph (delegation, SoD, limits, decay), risk scoring (13 dimensions, trust calibration, consequence class), conflict detection, `@governed` decorator, CLI, demo, audit logging, subscriptable record, empty authority default, instance isolation, and library boundary.
+79 tests covering: pipeline stages, advisory context, fail-closed behavior, policy evaluation (AND/OR groups, 14 operators, temporal conditions), authority graph (delegation, SoD, limits, decay), risk scoring (13 dimensions, trust calibration, consequence class), conflict detection, `@governed` decorator, CLI, demo, audit logging, subscriptable record, empty authority default, instance isolation, and library boundary.
 
 ## Requirements
 

{agentctrl-0.2.1 → agentctrl-0.2.2}/README.md

@@ -76,7 +76,7 @@ Those are institutional controls. They existed for human employees. They need to
 - **Fail-closed.** Any pipeline error produces BLOCK, never silent approval.
 - **Structural enforcement.** Policies are operator-based rule matching, not prompt instructions. Authority is graph traversal. Risk is weighted factor scoring. None of this is prompt engineering.
 
-> **Status:** 76 tests passing. Published on [PyPI](https://pypi.org/project/agentctrl/).
+> **Status:** 79 tests passing. Published on [PyPI](https://pypi.org/project/agentctrl/).
 
 ---
 
@@ -293,7 +293,7 @@ agent = Agent(role="analyst", tools=[governed_tool])
 
 ## Decision Pipeline
 
-Every action passes through 5 stages in order. Each can short-circuit.
+Every action passes through 5 stages in order. Each can short-circuit with BLOCK or ESCALATE. When a stage short-circuits, remaining stages still run as **ADVISORY** — their results are appended to the decision record for reviewer visibility but do not change the decision.
 
 ```
 Agent proposes action
@@ -305,6 +305,7 @@ Agent proposes action
     → Risk Scoring (how risky is this action in context?)
     → Conflict Detection (does this clash with other active workflows?)
     → Decision: ALLOW / ESCALATE / BLOCK
+         (+ ADVISORY stages from remaining pipeline on early exit)
 ```
 
 ### Policy Engine
@@ -400,7 +401,7 @@ result = await gateway.validate(proposal)
 python -m pytest tests/ -v
 ```
 
-76 tests covering: pipeline stages, fail-closed behavior, policy evaluation (AND/OR groups, 14 operators, temporal conditions), authority graph (delegation, SoD, limits, decay), risk scoring (13 dimensions, trust calibration, consequence class), conflict detection, `@governed` decorator, CLI, demo, audit logging, subscriptable record, empty authority default, instance isolation, and library boundary.
+79 tests covering: pipeline stages, advisory context, fail-closed behavior, policy evaluation (AND/OR groups, 14 operators, temporal conditions), authority graph (delegation, SoD, limits, decay), risk scoring (13 dimensions, trust calibration, consequence class), conflict detection, `@governed` decorator, CLI, demo, audit logging, subscriptable record, empty authority default, instance isolation, and library boundary.
 
 ## Requirements
 

{agentctrl-0.2.1 → agentctrl-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agentctrl"
-version = "0.2.1"
+version = "0.2.2"
 description = "Institutional control layer for AI agent actions — authority, policy, risk, and audit before execution."
 readme = "README.md"
 license = "Apache-2.0"

{agentctrl-0.2.1 → agentctrl-0.2.2}/src/agentctrl/runtime_gateway.py

@@ -19,7 +19,9 @@ Runtime Governance Model — Layer 1
 The pipeline evaluates every ActionProposal through 5 sequential decision
 stages (autonomy → policy → authority → risk → conflict).  Each stage can
 short-circuit with BLOCK or ESCALATE.  If all stages pass, the decision
-is ALLOW.
+is ALLOW.  On early ESCALATE/BLOCK, remaining stages still run as ADVISORY
+context — their results are appended to the decision record for reviewer
+visibility but do not change the decision.
 
 The kill switch is an optional pre-gate callback (`kill_switch_fn`) so
 the library works without platform dependencies.  Fail-closed: any
@@ -154,9 +156,8 @@ class RuntimeGateway:
         if stage1.status == "BLOCK":
             return self._make_decision(proposal, stages, "BLOCK", stage1.reason, 0.0, "LOW")
         if stage1.status == "ESCALATE":
-            risk = await self.risk_engine.score(proposal)
-            stages.append(PipelineStageResult("risk_scoring", "INFO",
-                                               {"risk_score": risk.score, "risk_level": risk.level}))
+            risk, advisory = await self._collect_advisory_context(proposal, from_stage=1)
+            stages.extend(advisory)
             return self._make_decision(proposal, stages, "ESCALATE", stage1.reason,
                                        risk.score, risk.level, escalated_to="approver_required")
 
@@ -164,7 +165,8 @@ class RuntimeGateway:
         stage2 = await self.policy_engine.validate(proposal)
         stages.append(stage2)
         if stage2.status in ("BLOCK", "ESCALATE"):
-            risk = await self.risk_engine.score(proposal)
+            risk, advisory = await self._collect_advisory_context(proposal, from_stage=2)
+            stages.extend(advisory)
             return self._make_decision(proposal, stages, stage2.status, stage2.reason,
                                        risk.score, risk.level)
 
@@ -172,7 +174,8 @@ class RuntimeGateway:
         stage3 = await self.authority_engine.resolve(proposal)
         stages.append(stage3)
         if stage3.status in ("BLOCK", "ESCALATE"):
-            risk = await self.risk_engine.score(proposal)
+            risk, advisory = await self._collect_advisory_context(proposal, from_stage=3)
+            stages.extend(advisory)
             escalated_to = stage3.details.get("escalate_to")
             return self._make_decision(proposal, stages, stage3.status, stage3.reason,
                                        risk.score, risk.level, escalated_to=escalated_to)
@@ -187,6 +190,8 @@ class RuntimeGateway:
         )
         stages.append(stage4)
         if stage4.status == "ESCALATE":
+            _risk, advisory = await self._collect_advisory_context(proposal, from_stage=4)
+            stages.extend(advisory)
             return self._make_decision(proposal, stages, "ESCALATE", stage4.reason,
                                        risk.score, risk.level)
 
@@ -202,6 +207,40 @@ class RuntimeGateway:
         reason = f"All validation stages passed. Action '{proposal.action_type}' approved for execution."
         return self._make_decision(proposal, stages, "ALLOW", reason, risk.score, risk.level)
 
+    async def _collect_advisory_context(
+        self, proposal: ActionProposal, from_stage: int,
+    ) -> tuple:
+        """Run remaining pipeline stages as non-decision ADVISORY context.
+
+        Gives the human reviewer visibility into what risk and conflict
+        would have said, even though an earlier stage already decided.
+        Returns (risk_result, list_of_advisory_stages).
+        ``from_stage`` is the stage number that triggered the early exit
+        (1=autonomy, 2=policy, 3=authority, 4=risk).
+        """
+        advisory_stages: list[PipelineStageResult] = []
+        if from_stage < 4:
+            risk = await self.risk_engine.score(proposal)
+            advisory_stages.append(
+                PipelineStageResult(
+                    "risk_scoring", "ADVISORY",
+                    {"risk_score": risk.score, "risk_level": risk.level, "factors": risk.factors},
+                    f"Advisory: Risk level {risk.level} (score: {risk.score:.2f})",
+                )
+            )
+        else:
+            risk = None
+        if from_stage < 5:
+            conflict = await self.conflict_detector.check(proposal)
+            advisory_stages.append(
+                PipelineStageResult(
+                    "conflict_detection", "ADVISORY",
+                    {"original_status": conflict.status, **(conflict.details or {})},
+                    f"Advisory: {conflict.reason}",
+                )
+            )
+        return risk, advisory_stages
+
     async def _check_autonomy(self, proposal: ActionProposal) -> PipelineStageResult:
         level = proposal.autonomy_level
         action = proposal.action_type.split(".")[0] if "." in proposal.action_type else proposal.action_type

{agentctrl-0.2.1 → agentctrl-0.2.2}/src/agentctrl/types.py

@@ -51,7 +51,7 @@ class ActionProposal:
 class PipelineStageResult:
     """Result from a single pipeline stage."""
     stage: str
-    status: str  # PASS | FAIL | ESCALATE | BLOCK
+    status: str  # PASS | FAIL | ESCALATE | BLOCK | ADVISORY
     details: dict = field(default_factory=dict)
     reason: str = ""
 

{agentctrl-0.2.1 → agentctrl-0.2.2}/tests/test_pipeline.py

@@ -84,7 +84,7 @@ async def test_hooks_called():
 
     decisions = []
     hooks = PipelineHooks(
-        on_decision=lambda d, p, s, l: decisions.append(d),
+        on_decision=lambda d, p, s, log: decisions.append(d),
     )
     gateway = RuntimeGateway(hooks=hooks)
     await gateway.validate(ActionProposal(
@@ -94,3 +94,63 @@ async def test_hooks_called():
         autonomy_level=2,
     ))
     assert len(decisions) == 1
+
+
+@pytest.mark.asyncio
+async def test_advisory_context_on_autonomy_escalate():
+    """Level 1 agent escalates at autonomy; risk + conflict run as ADVISORY."""
+    from agentctrl import RuntimeGateway, ActionProposal
+
+    gateway = RuntimeGateway()
+    result = await gateway.validate(ActionProposal(
+        agent_id="junior-agent",
+        action_type="email.send",
+        action_params={"to": "user@example.com"},
+        autonomy_level=1,
+    ))
+    assert result["decision"] == "ESCALATE"
+    stages = result["pipeline"]
+    advisory_stages = [s for s in stages if s["status"] == "ADVISORY"]
+    assert len(advisory_stages) == 2, f"Expected 2 advisory stages, got {len(advisory_stages)}"
+    advisory_names = {s["stage"] for s in advisory_stages}
+    assert "risk_scoring" in advisory_names
+    assert "conflict_detection" in advisory_names
+
+
+@pytest.mark.asyncio
+async def test_advisory_context_on_early_exit():
+    """Early BLOCK/ESCALATE still collects advisory risk + conflict stages."""
+    from agentctrl import RuntimeGateway, ActionProposal
+    from agentctrl.policy_engine import PolicyEngine
+
+    policies = [{"action_type": "delete.*", "effect": "BLOCK", "reason": "Deletes are forbidden"}]
+    gateway = RuntimeGateway(policy_engine=PolicyEngine(policies=policies))
+    result = await gateway.validate(ActionProposal(
+        agent_id="analyst",
+        action_type="delete.records",
+        action_params={},
+        autonomy_level=3,
+    ))
+    assert result["decision"] in ("BLOCK", "ESCALATE")
+    advisory_stages = [s for s in result["pipeline"] if s["status"] == "ADVISORY"]
+    assert len(advisory_stages) >= 1, "At least one ADVISORY stage expected"
+    advisory_names = {s["stage"] for s in advisory_stages}
+    assert "risk_scoring" in advisory_names or "conflict_detection" in advisory_names
+
+
+@pytest.mark.asyncio
+async def test_allow_has_no_advisory_stages():
+    """Normal ALLOW path has no ADVISORY stages — all stages run as real decisions."""
+    from agentctrl import RuntimeGateway, ActionProposal
+
+    gateway = RuntimeGateway()
+    result = await gateway.validate(ActionProposal(
+        agent_id="ap_analyst",
+        action_type="invoice.approve",
+        action_params={"amount": 1000},
+        autonomy_level=2,
+        trust_context={"total_actions": 10, "success_rate": 0.95},
+    ))
+    assert result["decision"] == "ALLOW"
+    advisory_stages = [s for s in result["pipeline"] if s["status"] == "ADVISORY"]
+    assert len(advisory_stages) == 0