axor-daemon 0.2.0__py3-none-any.whl

axor_daemon/__init__.py

@@ -0,0 +1,4 @@
+"""axor-daemon — process-isolated capability executor for axor-core."""
+from axor_daemon._version import get_version
+
+__version__ = get_version("axor-daemon")

axor_daemon/__main__.py

@@ -0,0 +1,205 @@
+"""
+CLI entry point for AxorDaemon.
+
+Usage:
+    python -m axor_daemon start [--socket PATH] [--policy NAME] [--log-level LEVEL]
+                                [--handler module.path:ClassName ...]
+    axor-daemon start [--socket PATH] [--policy NAME]
+
+Handlers are loaded at startup via --handler (repeatable). Each value is a
+dotted module path and class name separated by ':', e.g.:
+    --handler axor_claude.tools.read:ReadHandler
+    --handler axor_claude.tools.bash:BashHandler
+
+The class is instantiated with no arguments; its .name property is used as the
+tool name key. axor-daemon has no direct dependency on handler packages —
+they are imported dynamically at runtime.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import importlib
+import logging
+import signal
+import sys
+
+_DEFAULT_SOCKET = "~/.axor/daemon.sock"
+_DEFAULT_POLICY = "focused_generative"
+
+_POLICY_NAMES = {
+    "focused_readonly",
+    "focused_generative",
+    "focused_mutative",
+    "moderate_readonly",
+    "moderate_generative",
+    "moderate_mutative",
+    "expansive",
+}
+
+
+def _build_operator_policy(policy_name: str):
+    from axor_core.contracts.policy import (
+        TaskSignal, TaskComplexity, TaskNature,
+    )
+    from axor_core.policy.selector import PolicySelector
+
+    # Resolve name → signal → policy via PolicySelector
+    _name_to_signal = {
+        "focused_readonly":    (TaskComplexity.FOCUSED,   TaskNature.READONLY),
+        "focused_generative":  (TaskComplexity.FOCUSED,   TaskNature.GENERATIVE),
+        "focused_mutative":    (TaskComplexity.FOCUSED,   TaskNature.MUTATIVE),
+        "moderate_readonly":   (TaskComplexity.MODERATE,  TaskNature.READONLY),
+        "moderate_generative": (TaskComplexity.MODERATE,  TaskNature.GENERATIVE),
+        "moderate_mutative":   (TaskComplexity.MODERATE,  TaskNature.MUTATIVE),
+        "expansive":           (TaskComplexity.EXPANSIVE, TaskNature.MUTATIVE),
+    }
+    if policy_name not in _name_to_signal:
+        print(f"Unknown policy '{policy_name}'. Valid: {sorted(_POLICY_NAMES)}", file=sys.stderr)
+        sys.exit(1)
+
+    complexity, nature = _name_to_signal[policy_name]
+    signal = TaskSignal(
+        raw_input="",
+        complexity=complexity,
+        nature=nature,
+        estimated_scope=1,
+        requires_children=False,
+        requires_mutation=(nature == TaskNature.MUTATIVE),
+    )
+    return PolicySelector().select(signal)
+
+
+def _load_handlers(specs: list[str]) -> dict:
+    """
+    Load ToolHandler instances from 'module.path:ClassName' spec strings.
+    Each handler is instantiated with no arguments; its .name is the dict key.
+    """
+    handlers = {}
+    for spec in specs:
+        if ":" not in spec:
+            print(
+                f"Invalid --handler spec '{spec}'. Expected 'module.path:ClassName'.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        module_path, class_name = spec.rsplit(":", 1)
+        try:
+            module = importlib.import_module(module_path)
+        except ImportError as e:
+            print(f"Cannot import '{module_path}': {e}", file=sys.stderr)
+            sys.exit(1)
+        cls = getattr(module, class_name, None)
+        if cls is None:
+            print(
+                f"Class '{class_name}' not found in module '{module_path}'.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        handler = cls()
+        handlers[handler.name] = handler
+        logging.info("Registered handler '%s' from %s", handler.name, spec)
+    return handlers
+
+
+def _build_enforcer(operator_policy, handlers: dict, sandbox_root: str | None = None):
+    from axor_daemon.enforcer import DaemonEnforcer
+    return DaemonEnforcer(
+        operator_policy=operator_policy,
+        handlers=handlers,
+        sandbox_root=sandbox_root,
+    )
+
+
+async def _run(
+    socket_path: str,
+    policy_name: str,
+    handler_specs: list[str],
+    sandbox_root: str | None = None,
+) -> None:
+    from axor_daemon.server import DaemonServer
+
+    operator_policy = _build_operator_policy(policy_name)
+    handlers = _load_handlers(handler_specs)
+    enforcer = _build_enforcer(
+        operator_policy,
+        handlers=handlers,
+        sandbox_root=sandbox_root,
+    )
+    server = DaemonServer(enforcer=enforcer)
+    await server.start(socket_path)
+
+    loop = asyncio.get_running_loop()
+    stop_event = asyncio.Event()
+
+    def _handle_signal():
+        stop_event.set()
+
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        loop.add_signal_handler(sig, _handle_signal)
+
+    logging.info(
+        "AxorDaemon started — policy=%s socket=%s handlers=%s sandbox_root=%s",
+        policy_name, socket_path, sorted(handlers), sandbox_root or "<none>",
+    )
+
+    await stop_event.wait()
+    await server.stop()
+    logging.info("AxorDaemon stopped")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="axor-daemon",
+        description="AxorDaemon — process-isolated capability executor",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    start_p = sub.add_parser("start", help="Start the daemon")
+    start_p.add_argument(
+        "--socket", default=_DEFAULT_SOCKET,
+        help=f"Unix socket path (default: {_DEFAULT_SOCKET})",
+    )
+    start_p.add_argument(
+        "--policy", default=_DEFAULT_POLICY,
+        help=f"Operator policy ceiling (default: {_DEFAULT_POLICY}). "
+             f"Valid: {sorted(_POLICY_NAMES)}",
+    )
+    start_p.add_argument(
+        "--log-level", default="INFO",
+        choices=["DEBUG", "INFO", "WARNING", "ERROR"],
+    )
+    start_p.add_argument(
+        "--handler", dest="handlers", action="append", default=[],
+        metavar="MODULE:CLASS",
+        help=(
+            "Register a ToolHandler. Repeatable. Format: 'module.path:ClassName'. "
+            "Example: --handler axor_claude.tools.read:ReadHandler"
+        ),
+    )
+    start_p.add_argument(
+        "--sandbox-root",
+        default=os.environ.get("AXOR_DAEMON_SANDBOX_ROOT"),
+        help=(
+            "Optional filesystem root for daemon-side path args. "
+            "Also configurable via AXOR_DAEMON_SANDBOX_ROOT."
+        ),
+    )
+
+    args = parser.parse_args()
+
+    if args.command is None:
+        parser.print_help()
+        sys.exit(0)
+
+    logging.basicConfig(
+        level=getattr(logging, args.log_level),
+        format="%(asctime)s %(levelname)s %(name)s %(message)s",
+    )
+
+    asyncio.run(_run(args.socket, args.policy, args.handlers, args.sandbox_root))
+
+
+if __name__ == "__main__":
+    main()

axor_daemon/_version.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version as metadata_version
+from pathlib import Path
+import tomllib
+
+
+def get_version(distribution_name: str) -> str:
+    pyproject = Path(__file__).resolve().parents[1] / "pyproject.toml"
+    if pyproject.exists():
+        data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
+        return str(data["project"]["version"])
+    try:
+        return metadata_version(distribution_name)
+    except PackageNotFoundError:
+        return "0.0.0"

axor_daemon/enforcer.py

@@ -0,0 +1,143 @@
+"""
+DaemonEnforcer — validates tool calls against policy and executes approved ones.
+
+Two-ceiling enforcement:
+  1. client_allowed_tools  — derived by GovernedSession from session policy
+  2. operator_allowed_tools — derived from operator_policy set at daemon startup
+
+Tool executes only when approved by both. Operator ceiling cannot be escalated
+by the client — it is set once at daemon start and never modified per-connection.
+
+Args are never trusted raw from the client:
+  - tool name is validated against both ceilings before handler is called
+  - path-like string args are normalized independently, and when sandbox_root is
+    set they must resolve inside that root before handler execution
+  - handler execution is bounded by exec_timeout to prevent runaway tools
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from pathlib import Path
+from typing import Any
+
+from axor_core.capability.executor import ToolHandler
+from axor_core.capability.resolver import CapabilityResolver
+from axor_core.contracts.policy import ExecutionPolicy
+
+_log = logging.getLogger("axor.daemon.enforcer")
+
+# Path-like args the enforcer normalizes independently.
+# Handlers may have additional args — only these are path-normalized.
+_PATH_ARG_KEYS = frozenset({"path", "file", "filepath", "filename", "target"})
+
+# Default max seconds any single handler.execute() may run.
+_DEFAULT_EXEC_TIMEOUT = 60.0
+
+
+class DaemonEnforcer:
+    def __init__(
+        self,
+        operator_policy: ExecutionPolicy,
+        handlers: dict[str, ToolHandler],
+        exec_timeout: float = _DEFAULT_EXEC_TIMEOUT,
+        sandbox_root: str | None = None,
+    ) -> None:
+        self._operator_policy = operator_policy
+        self._handlers = handlers
+        self._exec_timeout = exec_timeout
+        self._sandbox_root = (
+            Path(sandbox_root).expanduser().resolve(strict=False)
+            if sandbox_root else None
+        )
+        resolver = CapabilityResolver()
+        caps = resolver.resolve(operator_policy)
+        self._operator_allowed: frozenset[str] = caps.allowed_tools
+
+    async def execute(
+        self,
+        call_id: str,
+        tool: str,
+        args: dict[str, Any],
+        client_allowed_tools: frozenset[str],
+    ) -> tuple[str, Any, str | None]:
+        """
+        Validate and execute a tool call.
+
+        Returns (decision, result, denial_reason):
+          decision: "approved" | "denied"
+          result:   tool output or None
+          denial_reason: str if denied, else None
+        """
+        # ceiling check — operator policy wins, evaluated daemon-side
+        if tool not in self._operator_allowed:
+            reason = f"tool '{tool}' not permitted by operator policy"
+            _log.info("DENIED call_id=%s tool=%s: %s", call_id, tool, reason)
+            return "denied", None, reason
+
+        # client check — session policy reported by client
+        if tool not in client_allowed_tools:
+            reason = f"tool '{tool}' not in session allowed_tools"
+            _log.info("DENIED call_id=%s tool=%s: %s", call_id, tool, reason)
+            return "denied", None, reason
+
+        handler = self._handlers.get(tool)
+        if handler is None:
+            reason = f"no handler registered for tool '{tool}'"
+            _log.warning("DENIED call_id=%s tool=%s: %s", call_id, tool, reason)
+            return "denied", None, reason
+
+        try:
+            safe_args = _normalize_path_args(args, sandbox_root=self._sandbox_root)
+        except ValueError as exc:
+            reason = str(exc)
+            _log.info("DENIED call_id=%s tool=%s: %s", call_id, tool, reason)
+            return "denied", None, reason
+
+        try:
+            result = await asyncio.wait_for(
+                handler.execute(safe_args), timeout=self._exec_timeout
+            )
+        except asyncio.TimeoutError:
+            reason = f"handler '{tool}' exceeded exec_timeout ({self._exec_timeout}s)"
+            _log.error("DENIED call_id=%s tool=%s: %s", call_id, tool, reason)
+            return "denied", None, reason
+
+        _log.debug("APPROVED call_id=%s tool=%s", call_id, tool)
+        return "approved", result, None
+
+
+def _normalize_path_args(
+    args: dict[str, Any],
+    sandbox_root: Path | None = None,
+) -> dict[str, Any]:
+    """
+    Return a copy of args with known path-like string values normalized.
+    Non-string values and unrecognized keys are passed through unchanged.
+    """
+    result = {}
+    for key, value in args.items():
+        if key in _PATH_ARG_KEYS and isinstance(value, str):
+            result[key] = _normalize_path(value, sandbox_root=sandbox_root)
+        else:
+            result[key] = value
+    return result
+
+
+def _normalize_path(value: str, sandbox_root: Path | None) -> str:
+    if sandbox_root is None:
+        return os.path.normpath(value)
+    path = Path(value).expanduser()
+    candidate = path if path.is_absolute() else sandbox_root / path
+    resolved = candidate.resolve(strict=False)
+    if resolved == sandbox_root:
+        return str(resolved)
+    try:
+        resolved.relative_to(sandbox_root)
+    except ValueError as exc:
+        raise ValueError(
+            f"path {str(path)!r} resolves outside daemon sandbox root"
+        ) from exc
+    return str(resolved)

axor_daemon/server.py

@@ -0,0 +1,179 @@
+"""
+DaemonServer — asyncio Unix socket server.
+
+One connection = one session. The server handles multiple concurrent
+connections; each runs in its own coroutine.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+import stat
+from typing import Any
+
+from axor_core.contracts.daemon import encode_message, read_message, PROTOCOL_VERSION
+
+from axor_daemon.enforcer import DaemonEnforcer
+
+_log = logging.getLogger("axor.daemon.server")
+
+_ALLOWED_MODES = {"library", "production", "strict"}
+
+# Seconds to wait for the next message from a connected client.
+# Prevents a stalled/malicious client from holding a session open indefinitely.
+_READ_TIMEOUT = 30.0
+
+# Max concurrent connections. Each connection is a coroutine; this caps memory.
+_MAX_CONNECTIONS = 64
+
+
+class DaemonServer:
+    def __init__(self, enforcer: DaemonEnforcer) -> None:
+        self._enforcer = enforcer
+        self._server: asyncio.Server | None = None
+        self._active_connections: set[asyncio.Task] = set()
+
+    async def start(self, socket_path: str) -> None:
+        socket_path = os.path.expanduser(socket_path)
+        os.makedirs(os.path.dirname(socket_path) or ".", exist_ok=True)
+
+        # Remove stale socket from a previous crash
+        try:
+            existing = os.lstat(socket_path)
+        except FileNotFoundError:
+            pass
+        else:
+            if not stat.S_ISSOCK(existing.st_mode):
+                raise FileExistsError(
+                    f"refusing to remove non-socket daemon path: {socket_path}"
+                )
+            os.unlink(socket_path)
+
+        self._server = await asyncio.start_unix_server(
+            self._handle_client, path=socket_path
+        )
+
+        # Restrict socket to owner only — any local process can connect otherwise.
+        os.chmod(socket_path, 0o600)
+
+        _log.info("AxorDaemon listening on %s (mode 600)", socket_path)
+
+    async def serve_forever(self) -> None:
+        if self._server is None:
+            raise RuntimeError("call start() before serve_forever()")
+        async with self._server:
+            await self._server.serve_forever()
+
+    async def stop(self) -> None:
+        if self._server is not None:
+            self._server.close()
+            await self._server.wait_closed()
+        for task in list(self._active_connections):
+            task.cancel()
+
+    # ── Per-connection handler ─────────────────────────────────────────────────
+
+    async def _handle_client(
+        self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter
+    ) -> None:
+        if len(self._active_connections) >= _MAX_CONNECTIONS:
+            _log.warning("max connections (%d) reached — rejecting", _MAX_CONNECTIONS)
+            writer.write(encode_message({"type": "rejected", "reason": "server at capacity"}))
+            try:
+                await writer.drain()
+                writer.close()
+            except Exception:
+                pass
+            return
+
+        peer = writer.get_extra_info("peername") or "unix"
+        task = asyncio.current_task()
+        self._active_connections.add(task)
+        _log.debug("connection from %s (active=%d)", peer, len(self._active_connections))
+        try:
+            await self._session(reader, writer)
+        except asyncio.IncompleteReadError:
+            pass  # client disconnected mid-message
+        except asyncio.TimeoutError:
+            _log.info("session timed out: %s", peer)
+        except Exception as exc:
+            _log.warning("session error from %s: %s", peer, exc)
+        finally:
+            self._active_connections.discard(task)
+            try:
+                writer.close()
+                await writer.wait_closed()
+            except Exception:
+                pass
+            _log.debug("connection closed: %s", peer)
+
+    async def _session(
+        self, reader: asyncio.StreamReader, writer: asyncio.StreamWriter
+    ) -> None:
+        # ── Handshake ──────────────────────────────────────────────────────────
+        hello = await asyncio.wait_for(read_message(reader), timeout=_READ_TIMEOUT)
+
+        client_version = hello.get("v")
+        if client_version != PROTOCOL_VERSION:
+            writer.write(encode_message({
+                "type": "rejected",
+                "reason": f"protocol version mismatch: client={client_version} server={PROTOCOL_VERSION}",
+            }))
+            await writer.drain()
+            return
+
+        if hello.get("type") != "hello":
+            writer.write(encode_message({
+                "type": "rejected",
+                "reason": f"expected hello, got {hello.get('type')!r}",
+            }))
+            await writer.drain()
+            return
+
+        mode = hello.get("mode", "library")
+        if mode not in _ALLOWED_MODES:
+            writer.write(encode_message({
+                "type": "rejected",
+                "reason": f"unknown mode {mode!r}",
+            }))
+            await writer.drain()
+            return
+
+        writer.write(encode_message({"type": "ready"}))
+        await writer.drain()
+
+        # ── Request loop ───────────────────────────────────────────────────────
+        while True:
+            msg = await asyncio.wait_for(read_message(reader), timeout=_READ_TIMEOUT)
+            msg_type = msg.get("type")
+
+            if msg_type == "bye":
+                break
+
+            if msg_type != "tool_call":
+                _log.warning("unexpected message type: %r", msg_type)
+                continue
+
+            call_id: str = msg.get("call_id", "")
+            tool: str = msg.get("tool", "")
+            args: dict[str, Any] = msg.get("args", {})
+            client_allowed: frozenset[str] = frozenset(msg.get("allowed_tools", []))
+
+            decision, result, denial_reason = await self._enforcer.execute(
+                call_id=call_id,
+                tool=tool,
+                args=args,
+                client_allowed_tools=client_allowed,
+            )
+
+            response = {
+                "type": "tool_result",
+                "call_id": call_id,
+                "decision": decision,
+                "result": result,
+                "denial_reason": denial_reason,
+            }
+            writer.write(encode_message(response))
+            await writer.drain()

axor_daemon-0.2.0.dist-info/METADATA

@@ -0,0 +1,264 @@
+Metadata-Version: 2.4
+Name: axor-daemon
+Version: 0.2.0
+Summary: Process-isolated capability executor for axor-core
+Project-URL: Repository, https://github.com/Bucha11/axor-daemon
+License: MIT
+Keywords: agents,ai,governance,llm,security
+Requires-Python: >=3.11
+Requires-Dist: axor-core<0.7,>=0.6.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# axor-daemon
+
+[![CI](https://github.com/Bucha11/axor-daemon/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Bucha11/axor-daemon/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/axor-daemon?cacheSeconds=300)](https://pypi.org/project/axor-daemon/)
+[![Python](https://img.shields.io/pypi/pyversions/axor-daemon?cacheSeconds=300)](https://pypi.org/project/axor-daemon/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+**Process-isolated capability executor for [axor-core](https://github.com/Bucha11/axor-core).**
+
+axor-core governs what agents are *allowed* to do. axor-daemon enforces it from *outside the agent process*.
+
+---
+
+## The Problem with Library-Only Governance
+
+When governance runs as a library in the same process as the agent, the enforcement boundary is Python-level. A compromised dependency, a monkey-patched import, or a hostile extension can bypass `CapabilityExecutor` without touching the governance logic at all.
+
+axor-daemon moves tool execution across a process boundary:
+
+```
+Agent process                      AxorDaemon process
+────────────────────────────       ─────────────────────────────────
+GovernedSession                    DaemonServer (mode 0600 socket)
+IntentLoop                           DaemonEnforcer
+DaemonCapabilityClient  ──────►        operator_policy (ceiling)
+  (no tool impls here)   socket         path normalization
+                        ◄──────        exec timeout per handler
+                                       approved result | DENIED
+```
+
+Tool implementations live only in the daemon. The agent process cannot call them directly — it has no code to do so. The Unix socket is the only path, and it is only accessible to the process owner.
+
+---
+
+## Enforcement Model
+
+Every tool call passes independent checks in the daemon:
+
+**1. Socket access** — the socket is created `0600`. Only the owner process may connect. Any other local process is rejected by the OS before the handshake begins.
+
+**2. Protocol version** — the handshake validates `PROTOCOL_VERSION` on both sides. A version mismatch is rejected immediately with an explicit error, not a silent protocol confusion.
+
+**3. Operator ceiling** — `operator_policy` is set at daemon startup by the operator and never modified per-connection. The daemon derives allowed tools from it independently — it does not trust the client's claim.
+
+**4. Client ceiling** — `allowed_tools` reported by the client's `GovernedSession`. Both the operator ceiling and the client ceiling must approve the tool. The client can only narrow below the operator ceiling, never escalate above it.
+
+**5. Arg normalization** — path-like args (`path`, `file`, `target`, etc.) are normalized with `os.path.normpath` by the daemon independently before being passed to any handler. A `../` traversal sequence in a client-supplied path cannot reach a handler unnormalized.
+
+**6. Exec timeout** — every handler execution is bounded by `exec_timeout` (default: 60s). A handler that exceeds the timeout returns `DENIED` — it does not hang the daemon session.
+
+```
+Client sends: tool="bash", allowed_tools=["bash", "read"]
+
+Operator policy = focused_readonly (allow_bash=False)
+  → DENIED  operator ceiling  "bash not permitted by operator policy"
+
+Client sends: tool="read", args={"path": "../../etc/passwd"}, allowed_tools=["read"]
+Operator policy = focused_readonly (allow_read=True)
+  → daemon normalizes path → "/etc/passwd"
+  → handler receives normalized args, never raw client string
+
+Client sends: tool="read", allowed_tools=[]   ← excluded read
+  → DENIED  session ceiling  "read not in session allowed_tools"
+```
+
+A client that sends an inflated `allowed_tools` list or crafted path args cannot bypass or escalate — both checks are evaluated daemon-side on independently derived state.
+
+---
+
+## Installation
+
+```bash
+pip install axor-daemon
+```
+
+Requires `axor-core >= 0.5.0, < 0.6`. Zero additional dependencies — stdlib `asyncio` only.
+
+---
+
+## Quick Start
+
+**1. Start the daemon**
+
+```bash
+axor-daemon start --policy focused_generative
+```
+
+The daemon loads the operator policy, creates `~/.axor/daemon.sock` with permissions `0600`, and begins accepting connections.
+
+**2. Use `DaemonCapabilityClient` instead of `CapabilityExecutor`**
+
+```python
+from axor_core.capability.daemon_client import DaemonCapabilityClient
+import axor_claude
+
+session = axor_claude.make_session(
+    api_key="sk-ant-...",
+    capability_executor=DaemonCapabilityClient(
+        socket_path="~/.axor/daemon.sock",
+        mode="production",
+    ),
+)
+
+result = await session.run("Write tests for the auth module")
+```
+
+No other changes. `DaemonCapabilityClient` exposes the same interface as `CapabilityExecutor`.
+
+---
+
+## Operator Policies
+
+The operator policy is the capability ceiling. Clients cannot exceed it.
+
+```bash
+axor-daemon start --policy focused_readonly     # read + search only, no writes
+axor-daemon start --policy focused_generative   # read + write, no bash (default)
+axor-daemon start --policy focused_mutative     # read + write + bash
+axor-daemon start --policy moderate_mutative    # broad context, bash, shallow children
+axor-daemon start --policy expansive            # full capability surface
+```
+
+| Policy | read | write | bash | search | children |
+|--------|------|-------|------|--------|----------|
+| `focused_readonly` | ✓ | — | — | ✓ | — |
+| `focused_generative` | ✓ | ✓ | — | ✓ | — |
+| `focused_mutative` | ✓ | ✓ | ✓ | ✓ | — |
+| `moderate_mutative` | ✓ | ✓ | ✓ | ✓ | shallow |
+| `expansive` | ✓ | ✓ | ✓ | ✓ | ✓ |
+
+---
+
+## CLI Reference
+
+```
+axor-daemon start [options]
+
+  --socket PATH      Unix socket path (default: ~/.axor/daemon.sock)
+  --policy NAME      Operator policy ceiling (default: focused_generative)
+  --log-level LEVEL  DEBUG | INFO | WARNING | ERROR (default: INFO)
+```
+
+---
+
+## Wire Protocol
+
+Communication is length-prefixed JSON over a Unix domain socket. Every message carries a protocol version field `"v"`. Version mismatches are rejected at handshake — there is no silent fallback.
+
+```
+Client → {"v": 1, "type": "hello", "mode": "production"}
+Server → {"v": 1, "type": "ready"}
+
+Client → {"v": 1, "type": "tool_call", "call_id": "a1b2c3", "tool": "read",
+           "args": {"path": "auth.py"}, "allowed_tools": ["read", "search"]}
+Server → {"v": 1, "type": "tool_result", "call_id": "a1b2c3",
+           "decision": "approved", "result": "...", "denial_reason": null}
+
+Client → {"v": 1, "type": "bye"}
+```
+
+**Framing:** 4-byte big-endian unsigned int (payload length) + JSON bytes. Maximum message size: 8 MB.
+
+**Backpressure:** the server enforces a maximum of 64 concurrent connections. Connections beyond this limit receive an immediate `rejected` response. Each connection has a `30s` read timeout — a stalled client does not hold a session indefinitely.
+
+One connection per session. If the connection is lost mid-session, `DaemonCapabilityClient` raises `DaemonUnavailableError` — fail-closed by design.
+
+---
+
+## Fail-Closed Guarantee
+
+If the daemon is unreachable, `DaemonCapabilityClient.execute()` raises `DaemonUnavailableError`. Execution stops. It never silently falls back to direct tool execution.
+
+```python
+from axor_core.errors.exceptions import DaemonUnavailableError
+
+try:
+    result = await session.run("audit the auth module")
+except DaemonUnavailableError as e:
+    # daemon not running — do not proceed
+    raise
+```
+
+---
+
+## Registering Tool Handlers
+
+Tool handlers live in the daemon, not in the client. Extend the daemon at startup:
+
+```python
+from axor_daemon.enforcer import DaemonEnforcer
+from axor_daemon.server import DaemonServer
+
+enforcer = DaemonEnforcer(
+    operator_policy=operator_policy,
+    exec_timeout=30.0,          # seconds per handler call, default 60
+    handlers={
+        "read":   MyReadHandler(),
+        "write":  MyWriteHandler(),
+        "bash":   MyBashHandler(),
+        "search": MySearchHandler(),
+    },
+)
+server = DaemonServer(enforcer=enforcer)
+await server.start("~/.axor/daemon.sock")
+await server.serve_forever()
+```
+
+`axor-claude` ships ready-made handlers for Claude tool use. Register them with the daemon at startup — not with the session.
+
+---
+
+## Known Limitations
+
+**Socket access is OS-level, not cryptographic.** Any process running as the same OS user may connect to the socket. For multi-user or container environments, run the agent in a separate OS user or apply additional access controls (e.g., systemd socket activation with `User=`).
+
+**Path normalization is not an allowlist.** `os.path.normpath` resolves `../` sequences so handlers always receive clean paths. It does not enforce which paths are allowed — that remains the handler's or operator's responsibility. Use `CapabilityLease` with `allowed_paths` for path allowlists.
+
+**Exec timeout kills slow handlers, not hanging syscalls.** `asyncio.wait_for` cancels the coroutine. If a handler blocks on a non-async call (e.g., a synchronous subprocess), the cancel will not interrupt it immediately. Use `asyncio.create_subprocess_exec` for shell commands inside handlers.
+
+**Trace is client-side.** Audit traces are written by the agent process, not the daemon. A compromised worker could suppress or mutate trace writes. Daemon-side audit logging is planned for a future release.
+
+For stronger guarantees, combine axor-daemon with OS-level sandboxing (seccomp, Landlock, container isolation) to restrict what the agent process can do even beyond the governance boundary. That is Level 2.
+
+---
+
+## Requirements
+
+- Python 3.11+
+- [`axor-core`](https://github.com/Bucha11/axor-core) >= 0.5.0
+- No additional dependencies — stdlib `asyncio` only
+
+---
+
+## Ecosystem
+
+| Package | Role |
+|---------|------|
+| [`axor-core`](https://github.com/Bucha11/axor-core) | Governance kernel — defines the contracts axor-daemon implements |
+| [`axor-daemon`](https://github.com/Bucha11/axor-daemon) | Process-isolated capability executor — this package |
+| [`axor-claude`](https://github.com/Bucha11/axor-claude) | Claude / Claude Code adapter — provides tool handlers |
+| [`axor-cli`](https://github.com/Bucha11/axor-cli) | Governed terminal runtime |
+| [`axor-memory-sqlite`](https://github.com/Bucha11/axor-memory-sqlite) | Cross-session memory (SQLite) |
+| [`axor-classifier-simple`](https://github.com/Bucha11/axor-classifier-simple) | ML task signal derivation (optional) |
+| [`axor-benchmarks`](https://github.com/Bucha11/axor-benchmarks) | Governance proof layer |
+
+---
+
+## License
+
+MIT

axor_daemon-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+axor_daemon/__init__.py,sha256=pIZrTV1zHikxix0rPa1eXbBKDT_iEl-v_-pHuYZ0koM,161
+axor_daemon/__main__.py,sha256=rgLiSnjx5060ApZUTsb13YqRMkry02fT5D-pey4JsuU,6525
+axor_daemon/_version.py,sha256=o4M0FB8h3-i2HR6VrTYRcbISOl18U5daSiDJDYfL5rY,536
+axor_daemon/enforcer.py,sha256=WU-j6DFHwV4XWDB8DeCCj-zw7uM52FLROQp1DVrYq44,5288
+axor_daemon/server.py,sha256=KorBhOZI6jT-PtcQMpMBJpu943LJb1n5RHSpOP2XDno,6593
+axor_daemon-0.2.0.dist-info/METADATA,sha256=GHIfwBm_qq8nzsDGjpo-yzmRkSxGvD0JrVSyOgapAd8,11223
+axor_daemon-0.2.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+axor_daemon-0.2.0.dist-info/entry_points.txt,sha256=eIj2g1gVZ2C1ZlmG1gSJhiGF1cjZOdXyy_VOIT9uOvw,58
+axor_daemon-0.2.0.dist-info/RECORD,,

axor_daemon-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

axor_daemon-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+axor-daemon = axor_daemon.__main__:main