corrlog-core 0.1.0__tar.gz

corrlog_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MSSAP Consulting
+
+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.

corrlog_core-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: corrlog-core
+Version: 0.1.0
+Summary: Agent Correction Record (ACR): cryptographically signed, tamper-evident records of agent self-disclosed mistakes
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=41.0
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.100; extra == "crewai"
+Provides-Extra: langchain
+Requires-Dist: langchain>=0.3; extra == "langchain"
+Provides-Extra: autogen
+Requires-Dist: autogen-core>=0.4; extra == "autogen"
+Provides-Extra: inspect
+Requires-Dist: inspect-ai>=0.3; extra == "inspect"
+Provides-Extra: proofagent
+Dynamic: license-file
+
+# corrlog — the Agent Correction Record (ACR) SDK
+
+**A cryptographically signed, tamper-evident record of corrections to agent actions,
+plus the corrective action taken.**
+
+`corrlog` extends the [AAR receipt spec](https://github.com/Cyberweasel777/agent-action-receipt-spec)
+with the missing half of the audit ledger: the **correction** — a signed, hash-chained
+record of "this prior action was found wrong, here's the fix and why." Receipts prove what
+happened; corrections make the fixes you made *attributable and tamper-evident*.
+
+- **`corrlog-core`** — framework-independent sign / verify / record / retract, Ed25519 over
+  canonical JSON (JCS), hash-chained. Single dependency: `cryptography`.
+- **`corrlog-crewai`** — drop-in CrewAI tool-call hooks (import-safe).
+- **`corrlog-langchain`** — `AgentMiddleware` for LangChain/LangGraph (native rollback via `Command`).
+- **`corrlog-claude-code`** — hook CLI + `hooks.json` plugin.
+- **`corrlog-autogen`** — `GuardedTool` wrapper over `run_json` (greenfield — no merged hook yet).
+- **`corrlog-proofagent`** — governance gate verdict (pass/review/block) → signed `check_failed`
+  receipt, signed by the *operator's* key (import-safe, parses dataclass or dict).
+- **`corrlog-inspect`** — `Hooks` extension for UK AISI Inspect: emits a signed receipt on an
+  `INCORRECT` score, agent identity from `spec.model` (extension package, no core changes).
+
+## Why
+
+Every agent vendor sells "our agent is reliable" and hides mistakes. An auditor cannot
+distinguish "a system that never erred" (impossible) from "a system that hid its errors."
+A signed correction log turns "we fixed it" into something *attributable and verifiable*.
+
+## The honesty rule
+
+An LLM does not reliably detect its own mistakes. So a correction is written when it is
+**detected** — by a supersede, a failed check, or a human flag — never by an LLM's unaided
+conscience. The key that holds authority over the action signs it either way (the agent's
+key, or the runtime that holds it). The signature proves *who recorded the correction*, not
+that the model recognised its own error.
+
+**Scope, stated plainly:** ACR proves *integrity* (records weren't altered) and
+*attribution* (which key signed). It does **not** prove *completeness* (that no mistakes
+were hidden) — a party that controls its own key can simply never write a correction. See
+SPEC.md §2 and §9 for the full boundary and the layers that narrow it.
+
+> **Security:** the independent verifier surfaced a key-substitution vulnerability in
+> self-authenticating verification; the spec now separates signature validity from trust
+> and supports pinned keys. See [SECURITY.md](SECURITY.md).
+
+| `trigger` | meaning |
+|---|---|
+| `supersede` | newer write replaced an older one |
+| `check_failed` | a guard/validator/policy rejected an action |
+| `human_flagged` | a person marked a prior output wrong |
+| `self_correction` | the agent detected it (weakest) |
+
+## Quick start
+
+```python
+from corrlog_core import generate_keypair, record, retract, verify, verify_chain, MemorySink
+
+priv, _ = generate_keypair()
+sink = MemorySink()
+
+# 1. Agent acts
+r1 = record(agent_id="forecast-agent", action_type="memory.write",
+            action_args={"project": "zespri", "topic": "yield"},
+            action_result={"yield": 1420}, private_key=priv)
+
+# 2. A check catches it's wrong -> signed correction
+c1 = retract(prior_record=r1, reason="wrong unit (kg vs tonne)",
+             trigger="check_failed", agent_id="forecast-agent", private_key=priv,
+             fix_type="replace", corrected_content={"yield": 1.42})
+
+# 3. Verify — offline, no trusted storage
+assert verify(c1)              # signature valid
+assert verify_chain([r1, c1])  # hash-linked, tamper-evident
+
+# 4. Tamper-evident: mutate the record and verification fails
+r1["reason"] = "tampered"
+assert not verify(r1)
+```
+
+Run the full demo: `python3 examples/demo.py`
+
+## CrewAI
+
+```python
+from corrlog_crewai import CrewAICorrectionLog, install
+from corrlog_core import generate_keypair, JsonlSink
+
+priv, _ = generate_keypair()
+log = CrewAICorrectionLog(JsonlSink("corrections.jsonl"), priv, agent_id="my-agent")
+install(log)   # registers before/after tool-call hooks globally
+
+# A human can flag a prior record wrong at any time:
+log.mark_wrong(prior_record, "wrong amount", fix_note="corrected")
+```
+
+## Compliance mapping (honest)
+
+ACR *supports* — it does not certify — EU AI Act duties for in-scope systems:
+Art 26(5) monitor/suspend, Art 26(6) log retention ≥6 months, Art 20 corrective actions,
+Art 73 serious-incident reporting; NIST AI RMF MANAGE 4.3. See SPEC.md §8 for what we can
+and cannot claim.
+
+## Status
+
+`corrlog-core` implemented and tested (core + adversarial + verifier-fixture suites).
+Adapters for CrewAI, LangChain/LangGraph, Claude Code, and AutoGen are implemented and
+import-safe. Two keyed-detector adapters ship too: `corrlog-proofagent` (governance gate
+→ signed receipt) and `corrlog-inspect` (Inspect `Hooks` extension), both tested against
+the real upstream APIs with real signing verified end-to-end. See SPEC.md for the
+integration points and §9 for the completeness roadmap (gapless sequence, external
+anchor, keyed trigger authorities).
+
+## Tests
+
+```
+python3 tests/test_core.py
+```

corrlog_core-0.1.0/README.md

@@ -0,0 +1,116 @@
+# corrlog — the Agent Correction Record (ACR) SDK
+
+**A cryptographically signed, tamper-evident record of corrections to agent actions,
+plus the corrective action taken.**
+
+`corrlog` extends the [AAR receipt spec](https://github.com/Cyberweasel777/agent-action-receipt-spec)
+with the missing half of the audit ledger: the **correction** — a signed, hash-chained
+record of "this prior action was found wrong, here's the fix and why." Receipts prove what
+happened; corrections make the fixes you made *attributable and tamper-evident*.
+
+- **`corrlog-core`** — framework-independent sign / verify / record / retract, Ed25519 over
+  canonical JSON (JCS), hash-chained. Single dependency: `cryptography`.
+- **`corrlog-crewai`** — drop-in CrewAI tool-call hooks (import-safe).
+- **`corrlog-langchain`** — `AgentMiddleware` for LangChain/LangGraph (native rollback via `Command`).
+- **`corrlog-claude-code`** — hook CLI + `hooks.json` plugin.
+- **`corrlog-autogen`** — `GuardedTool` wrapper over `run_json` (greenfield — no merged hook yet).
+- **`corrlog-proofagent`** — governance gate verdict (pass/review/block) → signed `check_failed`
+  receipt, signed by the *operator's* key (import-safe, parses dataclass or dict).
+- **`corrlog-inspect`** — `Hooks` extension for UK AISI Inspect: emits a signed receipt on an
+  `INCORRECT` score, agent identity from `spec.model` (extension package, no core changes).
+
+## Why
+
+Every agent vendor sells "our agent is reliable" and hides mistakes. An auditor cannot
+distinguish "a system that never erred" (impossible) from "a system that hid its errors."
+A signed correction log turns "we fixed it" into something *attributable and verifiable*.
+
+## The honesty rule
+
+An LLM does not reliably detect its own mistakes. So a correction is written when it is
+**detected** — by a supersede, a failed check, or a human flag — never by an LLM's unaided
+conscience. The key that holds authority over the action signs it either way (the agent's
+key, or the runtime that holds it). The signature proves *who recorded the correction*, not
+that the model recognised its own error.
+
+**Scope, stated plainly:** ACR proves *integrity* (records weren't altered) and
+*attribution* (which key signed). It does **not** prove *completeness* (that no mistakes
+were hidden) — a party that controls its own key can simply never write a correction. See
+SPEC.md §2 and §9 for the full boundary and the layers that narrow it.
+
+> **Security:** the independent verifier surfaced a key-substitution vulnerability in
+> self-authenticating verification; the spec now separates signature validity from trust
+> and supports pinned keys. See [SECURITY.md](SECURITY.md).
+
+| `trigger` | meaning |
+|---|---|
+| `supersede` | newer write replaced an older one |
+| `check_failed` | a guard/validator/policy rejected an action |
+| `human_flagged` | a person marked a prior output wrong |
+| `self_correction` | the agent detected it (weakest) |
+
+## Quick start
+
+```python
+from corrlog_core import generate_keypair, record, retract, verify, verify_chain, MemorySink
+
+priv, _ = generate_keypair()
+sink = MemorySink()
+
+# 1. Agent acts
+r1 = record(agent_id="forecast-agent", action_type="memory.write",
+            action_args={"project": "zespri", "topic": "yield"},
+            action_result={"yield": 1420}, private_key=priv)
+
+# 2. A check catches it's wrong -> signed correction
+c1 = retract(prior_record=r1, reason="wrong unit (kg vs tonne)",
+             trigger="check_failed", agent_id="forecast-agent", private_key=priv,
+             fix_type="replace", corrected_content={"yield": 1.42})
+
+# 3. Verify — offline, no trusted storage
+assert verify(c1)              # signature valid
+assert verify_chain([r1, c1])  # hash-linked, tamper-evident
+
+# 4. Tamper-evident: mutate the record and verification fails
+r1["reason"] = "tampered"
+assert not verify(r1)
+```
+
+Run the full demo: `python3 examples/demo.py`
+
+## CrewAI
+
+```python
+from corrlog_crewai import CrewAICorrectionLog, install
+from corrlog_core import generate_keypair, JsonlSink
+
+priv, _ = generate_keypair()
+log = CrewAICorrectionLog(JsonlSink("corrections.jsonl"), priv, agent_id="my-agent")
+install(log)   # registers before/after tool-call hooks globally
+
+# A human can flag a prior record wrong at any time:
+log.mark_wrong(prior_record, "wrong amount", fix_note="corrected")
+```
+
+## Compliance mapping (honest)
+
+ACR *supports* — it does not certify — EU AI Act duties for in-scope systems:
+Art 26(5) monitor/suspend, Art 26(6) log retention ≥6 months, Art 20 corrective actions,
+Art 73 serious-incident reporting; NIST AI RMF MANAGE 4.3. See SPEC.md §8 for what we can
+and cannot claim.
+
+## Status
+
+`corrlog-core` implemented and tested (core + adversarial + verifier-fixture suites).
+Adapters for CrewAI, LangChain/LangGraph, Claude Code, and AutoGen are implemented and
+import-safe. Two keyed-detector adapters ship too: `corrlog-proofagent` (governance gate
+→ signed receipt) and `corrlog-inspect` (Inspect `Hooks` extension), both tested against
+the real upstream APIs with real signing verified end-to-end. See SPEC.md for the
+integration points and §9 for the completeness roadmap (gapless sequence, external
+anchor, keyed trigger authorities).
+
+## Tests
+
+```
+python3 tests/test_core.py
+```

corrlog_core-0.1.0/corrlog_autogen/__init__.py

@@ -0,0 +1,112 @@
+"""corrlog-autogen — drop-in correction log for AutoGen agents.
+
+AutoGen has NO merged tool-call middleware as of this build (verified against the
+cloned source). The seams we need — `BaseTool.run_json()` / `Workbench.call_tool()` —
+are exactly what the still-open proposals target (#7405 GuardrailProvider, #7353 AAR
+receipts). So this adapter wraps `run_json` rather than relying on a shipped hook.
+
+Import-safe: if autogen is not installed, `is_available()` returns False and the
+wrapper class still imports.
+
+Usage (when autogen is installed):
+    from corrlog_autogen import GuardedTool
+    tool = GuardedTool(my_autogen_tool, sink, private_key, agent_id="agent-1")
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from corrlog_core import record, retract
+
+try:
+    from autogen_core.tools import BaseTool  # type: ignore
+    _AUTOGEN_AVAILABLE = True
+except Exception:  # pragma: no cover
+    _AUTOGEN_AVAILABLE = False
+
+
+def is_available() -> bool:
+    return _AUTOGEN_AVAILABLE
+
+
+class GuardedTool:
+    """Wraps an AutoGen tool, adding before/after correction-logging around `run_json`.
+
+    Structured to match the proposed GuardrailProvider signature from #7405, so it
+    upgrades cleanly when that lands upstream.
+    """
+
+    def __init__(self, tool, sink, private_key, agent_id: str, principal_id: str = "organization") -> None:
+        self._tool = tool
+        self.sink = sink
+        self.private_key = private_key
+        self.agent_id = agent_id
+        self.principal_id = principal_id
+
+    def __getattr__(self, name: str):
+        # Delegate everything else to the wrapped tool.
+        return getattr(self._tool, name)
+
+    @property
+    def name(self) -> str:
+        return getattr(self._tool, "name", "unknown_tool")
+
+    async def run_json(self, args, cancellation_token=None, call_id=None):
+        tool_name = self.name
+        rec = record(
+            agent_id=self.agent_id,
+            principal_id=self.principal_id,
+            action_type=f"autogen.tool.{tool_name}",
+            action_args=args if isinstance(args, dict) else {"args": args},
+            private_key=self.private_key,
+            metadata={"call_id": call_id} if call_id else None,
+        )
+        self.sink.append(rec)
+
+        try:
+            result = await self._tool.run_json(args, cancellation_token, call_id)
+        except Exception as e:  # noqa: BLE001
+            corr = retract(
+                prior_record=rec,
+                reason=f"tool raised: {e}",
+                trigger="check_failed",
+                agent_id=self.agent_id,
+                private_key=self.private_key,
+                principal_id=self.principal_id,
+                fix_type="replace",
+                fix_note=f"autogen tool {tool_name} raised",
+            )
+            self.sink.append(corr)
+            raise
+
+        # Result-level error detection (best-effort, framework-dependent shape).
+        if isinstance(result, dict) and result.get("error"):
+            corr = retract(
+                prior_record=rec,
+                reason=str(result["error"]),
+                trigger="check_failed",
+                agent_id=self.agent_id,
+                private_key=self.private_key,
+                principal_id=self.principal_id,
+                fix_type="replace",
+                fix_note=f"autogen tool {tool_name} errored",
+            )
+            self.sink.append(corr)
+
+        return result
+
+    def mark_wrong(self, prior_record: dict[str, Any], reason: str, fix_note: str | None = None) -> dict[str, Any]:
+        """Human-flag a prior record as wrong -> signed correction."""
+        corr = retract(
+            prior_record=prior_record,
+            reason=reason,
+            trigger="human_flagged",
+            agent_id=self.agent_id,
+            private_key=self.private_key,
+            principal_id=self.principal_id,
+            fix_type="replace",
+            fix_note=fix_note,
+        )
+        self.sink.append(corr)
+        return corr

corrlog_core-0.1.0/corrlog_claude_code/__init__.py

@@ -0,0 +1,8 @@
+"""corrlog-claude-code — plugin surface. The actual hook logic is in cli.py."""
+
+from __future__ import annotations
+
+
+def is_available() -> bool:
+    """Claude Code hooks are external processes — always 'available' if python is."""
+    return True

corrlog_core-0.1.0/corrlog_claude_code/cli.py

@@ -0,0 +1,147 @@
+"""corrlog-claude-code — CLI for Claude Code hooks.
+
+Invoked by hooks/hooks.json as an external process. Reads the hook's stdin JSON,
+emits a signed correction-log record.
+
+Modes:
+  - PreToolUse   : hash the tool input, mint an action id (emit to stderr-free stdout)
+  - PostToolUse  : hash the tool result, sign the action record
+  - human-flag   : `corrlog human-flag --receipt <id> --reason "..."` to flag wrong
+
+The key lives in $CORRLOG_KEY_PATH (a PEM/raw Ed25519 private key file).
+Records append to $CORRLOG_SINK (JSONL path) or ./corrections.jsonl.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from corrlog_core import generate_keypair, record, retract, JsonlSink
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import ed25519
+
+
+def _load_or_create_key(path: str):
+    if path and os.path.exists(path):
+        with open(path, "rb") as f:
+            return serialization.load_pem_private_key(f.read(), password=None)
+    priv = ed25519.Ed25519PrivateKey.generate()
+    if path:
+        with open(path, "wb") as f:
+            f.write(priv.private_bytes(
+                serialization.Encoding.PEM,
+                serialization.PrivateFormat.PKCS8,
+                serialization.NoEncryption(),
+            ))
+    return priv
+
+
+def _sink_path() -> str:
+    return os.environ.get("CORRLOG_SINK", os.path.join(os.getcwd(), "corrections.jsonl"))
+
+
+def _key_path() -> str:
+    return os.environ.get("CORRLOG_KEY_PATH", os.path.join(os.getcwd(), "corrlog_key.pem"))
+
+
+def _agent_id() -> str:
+    return os.environ.get("CORRLOG_AGENT_ID", "claude-code-agent")
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = argv if argv is not None else sys.argv[1:]
+
+    # Subcommand: human-flag
+    if argv and argv[0] == "human-flag":
+        p = argparse.ArgumentParser(prog="corrlog human-flag")
+        p.add_argument("--receipt", required=True)
+        p.add_argument("--reason", required=True)
+        p.add_argument("--fix-note")
+        args = p.parse_args(argv[1:])
+        priv = _load_or_create_key(_key_path())
+        sink = JsonlSink(_sink_path())
+        # Find the prior record.
+        prior = sink.get(args.receipt)
+        if prior is None:
+            print(json.dumps({"ok": False, "error": f"receipt {args.receipt} not found"}), file=sys.stderr)
+            return 1
+        corr = retract(
+            prior_record=prior, reason=args.reason, trigger="human_flagged",
+            agent_id=_agent_id(), private_key=priv, fix_type="replace", fix_note=args.fix_note,
+        )
+        sink.append(corr)
+        print(json.dumps({"ok": True, "correctionId": corr["correctionId"]}))
+        return 0
+
+    # Hook mode: read stdin JSON (Claude Code hook contract).
+    try:
+        data = json.load(sys.stdin)
+    except Exception:
+        data = {}
+
+    hook = data.get("hook_event_name", "")
+    tool_name = data.get("tool_name", "")
+    tool_input = data.get("tool_input", {})
+
+    priv = _load_or_create_key(_key_path())
+    sink = JsonlSink(_sink_path())
+
+    if hook == "PreToolUse":
+        rec = record(
+            agent_id=_agent_id(), action_type=f"claude.tool.{tool_name}",
+            action_args=tool_input if isinstance(tool_input, dict) else {"input": tool_input},
+            private_key=priv,
+        )
+        sink.append(rec)
+        # Allow the call; stash the action id in a sidecar file for PostToolUse.
+        _sidecar = os.path.join(os.getcwd(), ".corrlog_inflight.json")
+        try:
+            inflight = json.load(open(_sidecar)) if os.path.exists(_sidecar) else {}
+            inflight[tool_name] = rec["correctionId"]
+            json.dump(inflight, open(_sidecar, "w"))
+        except Exception:
+            pass
+        print(json.dumps({"continue": True}))
+
+    elif hook == "PostToolUse":
+        tool_result = data.get("tool_result", "")
+        _sidecar = os.path.join(os.getcwd(), ".corrlog_inflight.json")
+        prior_id = None
+        try:
+            inflight = json.load(open(_sidecar)) if os.path.exists(_sidecar) else {}
+            prior_id = inflight.pop(tool_name, None)
+            json.dump(inflight, open(_sidecar, "w"))
+        except Exception:
+            pass
+        rec = record(
+            agent_id=_agent_id(), action_type=f"claude.tool.{tool_name}",
+            action_args=tool_input if isinstance(tool_input, dict) else {"input": tool_input},
+            action_result=tool_result, private_key=priv,
+        )
+        sink.append(rec)
+        # Detect error in result -> check_failed correction.
+        if isinstance(tool_result, str) and any(
+            m in tool_result.lower() for m in ("error", "failed", "exception", "denied")
+        ):
+            corr = retract(
+                prior_record=rec, reason="tool returned error", trigger="check_failed",
+                agent_id=_agent_id(), private_key=priv, fix_type="replace",
+                fix_note=f"claude tool {tool_name} errored",
+            )
+            sink.append(corr)
+        print(json.dumps({"continue": True}))
+
+    else:
+        # Unhandled hook event: no-op, allow.
+        print(json.dumps({"continue": True}))
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

corrlog_core-0.1.0/corrlog_claude_code/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "command": "python3 -m corrlog_claude_code.cli"
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "command": "python3 -m corrlog_claude_code.cli"
+      }
+    ]
+  }
+}