clearframe 0.1.0__py3-none-any.whl

clearframe/__init__.py

@@ -0,0 +1,13 @@
+"""
+ClearFrame — Open-source AI agent protocol with auditability,
+goal monitoring, Reader/Actor isolation, and safety controls.
+
+A production-grade alternative to OpenClaw and MCP.
+"""
+
+from clearframe.core.config import ClearFrameConfig
+from clearframe.core.manifest import GoalManifest
+from clearframe.core.session import AgentSession
+
+__version__ = "0.1.0"
+__all__ = ["ClearFrameConfig", "GoalManifest", "AgentSession", "__version__"]

clearframe/cli.py

@@ -0,0 +1,131 @@
+"""ClearFrame CLI — clearframe init / audit-verify / audit-tail / ops-start / version"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+app = typer.Typer(
+    name="clearframe",
+    help="ClearFrame — AI agent protocol with auditability and safety controls.",
+    no_args_is_help=True,
+)
+console = Console()
+
+
+@app.command()
+def init(name: str = typer.Argument(..., help="Project name")) -> None:
+    """Initialise a new ClearFrame agent project."""
+    path = Path(name)
+    path.mkdir(exist_ok=True)
+    (path / "agent.py").write_text(
+        f'"""ClearFrame agent: {name}"""\n\n'
+        "import asyncio\n"
+        "from clearframe import AgentSession, GoalManifest, ClearFrameConfig\n"
+        "from clearframe.core.manifest import ToolPermission\n\n\n"
+        "async def main() -> None:\n"
+        "    config = ClearFrameConfig()\n"
+        "    manifest = GoalManifest(\n"
+        "        goal='Describe your agent goal here',\n"
+        "        permitted_tools=[ToolPermission(tool_name='web_search')],\n"
+        "    )\n"
+        "    async with AgentSession(config, manifest) as session:\n"
+        "        result = await session.call_tool('web_search', query='hello world')\n"
+        "        print(result)\n\n\n"
+        "if __name__ == '__main__':\n"
+        "    asyncio.run(main())\n"
+    )
+    (path / "clearframe.json").write_text(
+        json.dumps({"name": name, "version": "0.1.0"}, indent=2) + "\n"
+    )
+    console.print(f"[green]✓[/green] Initialised ClearFrame project: [bold]{name}[/bold]")
+    console.print(f"  Edit [cyan]{name}/agent.py[/cyan] to define your agent.")
+    console.print(f"  Run: [cyan]cd {name} && python agent.py[/cyan]")
+
+
+@app.command(name="audit-verify")
+def audit_verify(
+    session_id: str = typer.Option(None, "--session", "-s", help="Filter by session ID"),
+    log_path: Path = typer.Option(
+        Path.home() / ".clearframe" / "audit.log", "--log", help="Path to audit log"
+    ),
+) -> None:
+    """Verify HMAC chain integrity of the audit log."""
+    from clearframe.core.audit import AuditLog
+    from clearframe.core.config import AuditConfig
+
+    cfg = AuditConfig(log_path=log_path)
+    audit = AuditLog(cfg)
+    ok, errors = audit.verify()
+    if ok:
+        console.print("[green]✓ Audit log integrity verified — no tampering detected.[/green]")
+    else:
+        console.print(f"[red]✗ TAMPERING DETECTED — {len(errors)} error(s):[/red]")
+        for err in errors:
+            console.print(f"  [red]{err}[/red]")
+        raise typer.Exit(code=1)
+
+
+@app.command(name="audit-tail")
+def audit_tail(
+    n: int = typer.Option(20, "--lines", "-n", help="Number of entries to show"),
+    log_path: Path = typer.Option(
+        Path.home() / ".clearframe" / "audit.log", "--log", help="Path to audit log"
+    ),
+) -> None:
+    """Show recent audit log entries."""
+    from clearframe.core.audit import AuditLog
+    from clearframe.core.config import AuditConfig
+
+    cfg = AuditConfig(log_path=log_path)
+    audit = AuditLog(cfg)
+    entries = audit.tail(n)
+    if not entries:
+        console.print("[dim]No audit entries found.[/dim]")
+        return
+    table = Table(title=f"Last {n} Audit Entries", show_lines=True)
+    table.add_column("Seq", style="dim", width=6)
+    table.add_column("Event", style="cyan")
+    table.add_column("Session", style="dim", width=14)
+    table.add_column("Timestamp", style="dim")
+    for e in entries:
+        table.add_row(
+            str(e.get("seq", "")),
+            e.get("event_type", ""),
+            str(e.get("session_id", ""))[:12] + "…",
+            str(e.get("timestamp", ""))[:19],
+        )
+    console.print(table)
+
+
+@app.command(name="ops-start")
+def ops_start(
+    host: str = typer.Option("127.0.0.1", "--host"),
+    port: int = typer.Option(7477, "--port"),
+) -> None:
+    """Start the AgentOps control plane server."""
+    import uvicorn
+    from clearframe.core.config import OpsConfig
+    from clearframe.ops.server import create_ops_app, _ops_token
+
+    config = OpsConfig(host=host, port=port)
+    ops_app = create_ops_app(config)
+    console.print(f"[green]✓ ClearFrame AgentOps starting at http://{host}:{port}[/green]")
+    console.print(f"  [yellow]Auth token:[/yellow] {_ops_token}")
+    console.print("  [dim]Keep this token private — it grants full control.[/dim]")
+    uvicorn.run(ops_app, host=host, port=port)
+
+
+@app.command()
+def version() -> None:
+    """Show ClearFrame version."""
+    from clearframe import __version__
+    console.print(f"ClearFrame v{__version__}")
+
+
+if __name__ == "__main__":
+    app()

clearframe/core/audit.py

@@ -0,0 +1,159 @@
+"""
+ClearFrame HMAC-Chained Audit Log
+
+Every event is linked to the previous via HMAC-SHA256.
+Deleting or editing any entry breaks the chain — detectable immediately.
+
+Contrast with OpenClaw/MCP: no audit trail exists. Post-incident
+forensics is impossible.
+
+Format: newline-delimited JSON (.jsonl)
+Each line:
+  {
+    "seq": 1,
+    "timestamp": "2026-04-12T03:00:00Z",
+    "event_type": "SESSION_START",
+    "session_id": "abc-123",
+    "data": {...},
+    "prev_hmac": "0000...0000",   // "0" * 64 for seq=1
+    "hmac": "sha256-hex"
+  }
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+import os
+import time
+from enum import Enum
+from pathlib import Path
+from typing import Any
+
+from clearframe.core.config import AuditConfig
+
+
+class EventType(str, Enum):
+    SESSION_START         = "SESSION_START"
+    SESSION_END           = "SESSION_END"
+    TOOL_CALL_REQUESTED   = "TOOL_CALL_REQUESTED"
+    TOOL_CALL_APPROVED    = "TOOL_CALL_APPROVED"
+    TOOL_CALL_BLOCKED     = "TOOL_CALL_BLOCKED"
+    TOOL_CALL_COMPLETED   = "TOOL_CALL_COMPLETED"
+    GOAL_SCORE            = "GOAL_SCORE"
+    CONTEXT_HASH          = "CONTEXT_HASH"
+    VAULT_ACCESS          = "VAULT_ACCESS"
+    PLUGIN_LOADED         = "PLUGIN_LOADED"
+    SECURITY_ALERT        = "SECURITY_ALERT"
+    OPERATOR_DECISION     = "OPERATOR_DECISION"
+
+
+_DEFAULT_SECRET = b"clearframe-default-audit-secret-change-in-production"
+
+
+class AuditLog:
+    """
+    HMAC-SHA256 chained append-only audit log.
+
+    Each entry's HMAC covers: seq + timestamp + event_type + session_id + data + prev_hmac.
+    Verifying the chain detects any insertion, deletion, or modification.
+    """
+
+    def __init__(self, config: AuditConfig) -> None:
+        self._config = config
+        self._secret = os.environb.get(
+            config.hmac_secret_env.encode(), _DEFAULT_SECRET
+        )
+        self._seq = 0
+        self._prev_hmac = "0" * 64
+        if config.enabled and config.log_path.exists():
+            entries = self._read_all()
+            if entries:
+                last = entries[-1]
+                self._seq = last.get("seq", 0)
+                self._prev_hmac = last.get("hmac", "0" * 64)
+
+    def write(
+        self,
+        event_type: EventType,
+        session_id: str,
+        data: dict[str, Any],
+    ) -> dict[str, Any]:
+        self._seq += 1
+        timestamp = time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
+        entry: dict[str, Any] = {
+            "seq": self._seq,
+            "timestamp": timestamp,
+            "event_type": event_type.value,
+            "session_id": session_id,
+            "data": data,
+            "prev_hmac": self._prev_hmac,
+        }
+        entry["hmac"] = self._compute_hmac(entry)
+        self._prev_hmac = entry["hmac"]
+        if self._config.enabled:
+            self._config.log_path.parent.mkdir(parents=True, exist_ok=True)
+            with open(self._config.log_path, "a", encoding="utf-8") as f:
+                f.write(json.dumps(entry) + "\n")
+        return entry
+
+    def verify(self) -> tuple[bool, list[str]]:
+        """Verify the full HMAC chain. Returns (ok, list_of_errors)."""
+        errors: list[str] = []
+        entries = self._read_all()
+        prev = "0" * 64
+        for entry in entries:
+            stored_hmac = entry.get("hmac", "")
+            check = {k: v for k, v in entry.items() if k != "hmac"}
+            check["prev_hmac"] = prev
+            expected = self._compute_hmac(check)
+            if not hmac.compare_digest(stored_hmac, expected):
+                errors.append(
+                    f"Chain broken at seq={entry.get('seq')} "
+                    f"event={entry.get('event_type')} — HMAC mismatch"
+                )
+            prev = stored_hmac
+        return len(errors) == 0, errors
+
+    def query(
+        self,
+        session_id: str | None = None,
+        event_type: str | None = None,
+        limit: int = 100,
+    ) -> list[dict[str, Any]]:
+        entries = self._read_all()
+        if session_id:
+            entries = [e for e in entries if e.get("session_id") == session_id]
+        if event_type:
+            entries = [e for e in entries if e.get("event_type") == event_type]
+        return entries[-limit:]
+
+    def tail(self, n: int = 20) -> list[dict[str, Any]]:
+        return self._read_all()[-n:]
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    def _compute_hmac(self, entry: dict[str, Any]) -> str:
+        canonical = json.dumps(
+            {k: entry[k] for k in sorted(entry.keys()) if k != "hmac"},
+            sort_keys=True,
+            separators=(",", ":"),
+        ).encode()
+        return hmac.new(self._secret, canonical, hashlib.sha256).hexdigest()
+
+    def _read_all(self) -> list[dict[str, Any]]:
+        if not self._config.log_path.exists():
+            return []
+        entries = []
+        with open(self._config.log_path, encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if line:
+                    try:
+                        entries.append(json.loads(line))
+                    except json.JSONDecodeError:
+                        pass
+        return entries

clearframe/core/config.py

@@ -0,0 +1,52 @@
+"""
+ClearFrame Configuration
+
+Secure defaults throughout. Every dangerous option is OFF by default.
+Contrast with OpenClaw which binds to 0.0.0.0 and requires no auth.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from pydantic import BaseModel, Field
+
+
+class VaultConfig(BaseModel):
+    vault_path: Path = Field(default=Path("~/.clearframe/vault.enc").expanduser())
+    salt_path: Path = Field(default=Path("~/.clearframe/vault.salt").expanduser())
+    pbkdf2_iterations: int = 600_000   # OWASP 2024 minimum is 210,000 — we exceed it
+
+
+class AuditConfig(BaseModel):
+    log_path: Path = Field(default=Path("~/.clearframe/audit.log").expanduser())
+    enabled: bool = True
+    hmac_secret_env: str = "CLEARFRAME_AUDIT_SECRET"
+
+
+class RTLConfig(BaseModel):
+    rtl_path: Path = Field(default=Path("~/.clearframe/rtl").expanduser())
+    enabled: bool = True
+
+
+class GoalMonitorConfig(BaseModel):
+    alignment_threshold: float = 0.55       # Below this → block or queue
+    auto_approve_threshold: float = 0.85    # Above this → auto-approve
+    pause_on_ambiguous: bool = True         # True → queue; False → block
+    max_consecutive_low_scores: int = 3     # Suspend session after N low scores
+
+
+class OpsConfig(BaseModel):
+    host: str = "127.0.0.1"    # Localhost only — never 0.0.0.0 by default
+    port: int = 7477
+    require_auth: bool = True
+    cors_origins: list[str] = Field(default_factory=lambda: ["http://localhost:3000"])
+
+
+class ClearFrameConfig(BaseModel):
+    vault: VaultConfig = Field(default_factory=VaultConfig)
+    audit: AuditConfig = Field(default_factory=AuditConfig)
+    rtl: RTLConfig = Field(default_factory=RTLConfig)
+    goal_monitor: GoalMonitorConfig = Field(default_factory=GoalMonitorConfig)
+    ops: OpsConfig = Field(default_factory=OpsConfig)
+    # Never bind to all interfaces by default (OpenClaw CVE-2024-6940 root cause)
+    allow_remote_connections: bool = False

clearframe/core/manifest.py

@@ -0,0 +1,88 @@
+"""
+ClearFrame GoalManifest
+
+Every agent session MUST declare:
+  - A plain-English goal
+  - The exact set of tools it is permitted to use
+  - Resource scope (allowed domains, paths)
+  - Whether file writes and code execution are permitted
+
+This declaration is written to the audit log at session start and
+evaluated by the Goal Monitor on every tool call.
+
+Contrast with OpenClaw/MCP: there is no concept of a declared goal.
+The runtime has no idea what the agent is supposed to be doing,
+so it cannot detect drift.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+from pydantic import BaseModel, Field
+
+
+class ResourceScope(BaseModel):
+    """Defines the external resources an agent is permitted to access."""
+    allowed_domains: list[str] = Field(
+        default_factory=list,
+        description=(
+            "Domains the agent may fetch. Supports * wildcard. "
+            "Empty list = unrestricted (logged but not blocked)."
+        ),
+    )
+    allowed_paths: list[str] = Field(
+        default_factory=list,
+        description="Filesystem paths the agent may read. Empty = none.",
+    )
+    allowed_write_paths: list[str] = Field(
+        default_factory=list,
+        description="Filesystem paths the agent may write. Empty = none.",
+    )
+
+
+class ToolPermission(BaseModel):
+    """Declares permission for a single tool."""
+    tool_name: str
+    max_calls_per_session: Optional[int] = None   # None = unlimited
+    require_approval: bool = False                 # True = always queue for operator
+    allowed_arg_patterns: dict[str, str] = Field(
+        default_factory=dict,
+        description="Optional regex patterns for arg validation. e.g. {'query': '^[a-zA-Z ]+$'}",
+    )
+
+
+class GoalManifest(BaseModel):
+    """
+    The complete declaration of what an agent session is allowed to do.
+
+    Immutable once a session starts. Any attempt to modify it after
+    session start raises ManifestLockError.
+    """
+
+    goal: str = Field(
+        ...,
+        description="Plain-English statement of what this agent session should accomplish.",
+        min_length=10,
+        max_length=2000,
+    )
+    permitted_tools: list[ToolPermission] = Field(
+        default_factory=list,
+        description="Explicit allowlist of tools. Tools not listed are blocked.",
+    )
+    resource_scope: ResourceScope = Field(default_factory=ResourceScope)
+    allow_file_write: bool = False
+    allow_code_execution: bool = False
+    max_steps: Optional[int] = 50
+    auto_pause_on_drift: bool = True
+
+    # Internal — set by AgentSession on start
+    _locked: bool = False
+
+    def lock(self) -> None:
+        object.__setattr__(self, "_locked", True)
+
+    def is_tool_permitted(self, tool_name: str) -> bool:
+        return any(p.tool_name == tool_name for p in self.permitted_tools)
+
+    def get_tool_permission(self, tool_name: str) -> Optional[ToolPermission]:
+        return next((p for p in self.permitted_tools if p.tool_name == tool_name), None)

clearframe/core/session.py

@@ -0,0 +1,192 @@
+"""
+ClearFrame AgentSession — the main runtime orchestrator.
+
+Coordinates:
+  1. GoalManifest declaration and lock
+  2. Vault (credentials)
+  3. Reader/Actor isolation layer
+  4. Goal Monitor (alignment scoring on every tool call)
+  5. RTL (reasoning trace recording)
+  6. Audit log (HMAC-chained, every event)
+  7. Context Feed Auditor (hash every context chunk)
+"""
+
+from __future__ import annotations
+
+import hashlib
+import time
+import uuid
+from typing import Any, Callable
+
+from clearframe.core.audit import AuditLog, EventType
+from clearframe.core.config import ClearFrameConfig
+from clearframe.core.manifest import GoalManifest
+from clearframe.core.vault import Vault
+from clearframe.monitor.goal_monitor import GoalMonitor, Disposition
+from clearframe.monitor.rtl import RTL
+from clearframe.gateway.isolation import MessagePipe, ReaderSandbox, ActorSandbox
+
+
+class SessionError(Exception):
+    pass
+
+
+class AgentSession:
+    """
+    A single ClearFrame agent session.
+
+    Usage:
+        config = ClearFrameConfig()
+        manifest = GoalManifest(
+            goal="Search for AI safety papers and summarise them",
+            permitted_tools=[ToolPermission(tool_name="web_search", max_calls_per_session=5)],
+        )
+        async with AgentSession(config, manifest) as session:
+            result = await session.call_tool("web_search", query="AI safety 2026")
+    """
+
+    def __init__(
+        self,
+        config: ClearFrameConfig,
+        manifest: GoalManifest,
+        tool_registry: dict[str, Callable] | None = None,
+    ) -> None:
+        self._config = config
+        self._manifest = manifest
+        self._tools = tool_registry or {}
+        self._session_id = str(uuid.uuid4())
+        self._start_time = time.time()
+
+        self._audit   = AuditLog(config.audit)
+        self._vault   = Vault(config.vault)
+        self._monitor = GoalMonitor(manifest, config.goal_monitor)
+        self._rtl     = RTL(self._session_id, config.rtl)
+
+        self._pipe   = MessagePipe()
+        self._reader = ReaderSandbox(self._session_id, self._pipe)
+        self._actor  = ActorSandbox(self._session_id, self._pipe, self._tools)
+
+        self._context_chunks: list[dict] = []
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def start(self) -> None:
+        self._manifest.lock()
+        self._audit.write(EventType.SESSION_START, self._session_id, {
+            "manifest_goal": self._manifest.goal[:200],
+            "permitted_tools": [p.tool_name for p in self._manifest.permitted_tools],
+            "allow_file_write": self._manifest.allow_file_write,
+            "allow_code_execution": self._manifest.allow_code_execution,
+            "max_steps": self._manifest.max_steps,
+        })
+
+    async def end(self, outcome: str = "completed") -> None:
+        elapsed = time.time() - self._start_time
+        self._audit.write(EventType.SESSION_END, self._session_id, {
+            "outcome": outcome,
+            "elapsed_seconds": round(elapsed, 2),
+            "monitor_stats": self._monitor.stats(),
+            "context_chunks": len(self._context_chunks),
+        })
+        self._vault.lock()
+
+    # ------------------------------------------------------------------
+    # Tool call — main user-facing method
+    # ------------------------------------------------------------------
+
+    async def call_tool(self, tool_name: str, **kwargs: Any) -> Any:
+        """
+        Request a tool call. The Goal Monitor evaluates alignment first.
+        Only approved / auto-approved calls reach the Actor sandbox.
+        """
+        args = dict(kwargs)
+        self._rtl.record("tool_call", f"{tool_name}({args})")
+
+        scored = self._monitor.evaluate(tool_name, args)
+        self._audit.write(EventType.GOAL_SCORE, self._session_id, {
+            "tool_name": tool_name,
+            "score": scored.alignment_score,
+            "disposition": scored.disposition.value,
+            "reasons": scored.reasons,
+        })
+
+        if scored.disposition == Disposition.BLOCK:
+            self._audit.write(EventType.TOOL_CALL_BLOCKED, self._session_id, {
+                "tool_name": tool_name, "reasons": scored.reasons,
+            })
+            raise SessionError(
+                f"[ClearFrame] Tool '{tool_name}' BLOCKED. "
+                f"Score: {scored.alignment_score}. Reasons: {scored.reasons}"
+            )
+
+        if scored.disposition == Disposition.QUEUE:
+            self._audit.write(EventType.TOOL_CALL_REQUESTED, self._session_id, {
+                "tool_name": tool_name,
+                "score": scored.alignment_score,
+                "status": "pending_operator_approval",
+            })
+            raise SessionError(
+                f"[ClearFrame] Tool '{tool_name}' queued for operator approval "
+                f"(score: {scored.alignment_score}). Check AgentOps dashboard."
+            )
+
+        # Approved — execute via Actor sandbox
+        self._audit.write(EventType.TOOL_CALL_APPROVED, self._session_id, {
+            "tool_name": tool_name, "score": scored.alignment_score,
+        })
+        result = await self._actor.execute_approved_call(tool_name, args)
+        self._audit.write(EventType.TOOL_CALL_COMPLETED, self._session_id, {
+            "tool_name": tool_name, "result_preview": str(result)[:200],
+        })
+        return result
+
+    # ------------------------------------------------------------------
+    # Context Feed Auditor
+    # ------------------------------------------------------------------
+
+    async def ingest_context(self, content: str, source: str) -> str:
+        """
+        Ingest untrusted content through the Reader sandbox.
+        Source-tagged and SHA-256 hashed into the audit log.
+        Returns the content hash.
+        """
+        content_hash = hashlib.sha256(content.encode()).hexdigest()
+        self._audit.write(EventType.CONTEXT_HASH, self._session_id, {
+            "source": source, "length": len(content), "sha256": content_hash,
+        })
+        await self._reader.ingest_text(content, source)
+        self._context_chunks.append({"source": source, "hash": content_hash})
+        return content_hash
+
+    # ------------------------------------------------------------------
+    # Context manager
+    # ------------------------------------------------------------------
+
+    async def __aenter__(self) -> "AgentSession":
+        await self.start()
+        return self
+
+    async def __aexit__(self, exc_type: Any, *_: Any) -> None:
+        await self.end("error" if exc_type else "completed")
+
+    # ------------------------------------------------------------------
+    # Properties
+    # ------------------------------------------------------------------
+
+    @property
+    def session_id(self) -> str:
+        return self._session_id
+
+    @property
+    def audit(self) -> AuditLog:
+        return self._audit
+
+    @property
+    def rtl(self) -> RTL:
+        return self._rtl
+
+    @property
+    def monitor(self) -> GoalMonitor:
+        return self._monitor