axor-cli 0.1.0__py3-none-any.whl

axor_cli/__init__.py

@@ -0,0 +1,3 @@
+"""axor-cli — governed agent sessions from the terminal."""
+from axor_cli._version import __version__
+__all__ = ["__version__"]

axor_cli/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

axor_cli/adapters.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+"""
+Adapter registry for axor-cli.
+
+Adapters are loaded lazily — axor-claude / axor-openai are optional
+dependencies. Missing adapter gives a helpful install message.
+"""
+
+from typing import Any
+from axor_core import GovernedSession, CapabilityExecutor
+
+
+# Map of adapter name → module path + setup function
+_REGISTRY: dict[str, dict[str, Any]] = {
+    "claude": {
+        "module":   "axor_claude",
+        "install":  "pip install axor-claude",
+        "env_var":  "ANTHROPIC_API_KEY",
+        "models":   ["claude-sonnet-4-5", "claude-opus-4-5", "claude-haiku-4-5"],
+        "default_model": "claude-sonnet-4-5",
+    },
+    "openai": {
+        "module":   "axor_openai",
+        "install":  "pip install axor-openai",
+        "env_var":  "OPENAI_API_KEY",
+        "models":   ["gpt-4o", "gpt-4o-mini"],
+        "default_model": "gpt-4o",
+    },
+}
+
+
+def list_adapters() -> list[str]:
+    return list(_REGISTRY.keys())
+
+
+def is_available(adapter: str) -> bool:
+    """Check if adapter package is installed."""
+    info = _REGISTRY.get(adapter)
+    if not info:
+        return False
+    try:
+        __import__(info["module"])
+        return True
+    except ImportError:
+        return False
+
+
+def get_install_hint(adapter: str) -> str:
+    info = _REGISTRY.get(adapter, {})
+    return info.get("install", f"pip install axor-{adapter}")
+
+
+def build_session(
+    adapter: str,
+    api_key: str | None = None,
+    model:   str | None = None,
+    tools:   tuple[str, ...] = ("read", "write", "bash", "search", "glob"),
+    soft_token_limit: int | None = None,
+    system_prompt: str | None = None,
+    load_skills: bool = True,
+    load_plugins: bool = True,
+) -> GovernedSession:
+    """
+    Import the adapter package and build a GovernedSession.
+    Raises ImportError with install hint if package not installed.
+    """
+    info = _REGISTRY.get(adapter)
+    if not info:
+        available = ", ".join(_REGISTRY.keys())
+        raise ValueError(f"Unknown adapter: '{adapter}'. Available: {available}")
+
+    try:
+        mod = __import__(info["module"])
+    except ImportError:
+        raise ImportError(
+            f"Adapter '{adapter}' is not installed.\n"
+            f"Install it with: {info['install']}"
+        )
+
+    # adapters expose make_session() as the standard factory
+    if not hasattr(mod, "make_session"):
+        raise AttributeError(
+            f"Adapter '{adapter}' ({info['module']}) does not expose make_session(). "
+            "Check your axor adapter version."
+        )
+
+    kwargs: dict[str, Any] = {
+        "api_key":     api_key,
+        "tools":       tools,
+        "load_skills": load_skills,
+        "load_plugins": load_plugins,
+    }
+    if soft_token_limit is not None:
+        kwargs["soft_token_limit"] = soft_token_limit
+
+    # model and system_prompt are passed to the executor inside make_session
+    # adapters should accept **session_kwargs and forward to their executor
+    if model:
+        kwargs["model"] = model
+    if system_prompt:
+        kwargs["system_prompt"] = system_prompt
+
+    try:
+        return mod.make_session(**kwargs)
+    except ImportError as e:
+        # adapter's underlying SDK (e.g. anthropic) not installed
+        raise ImportError(
+            f"Adapter '{adapter}' requires additional dependencies.\n"
+            f"  {e}\n"
+            f"  Install with: {info['install']}"
+        ) from e
+
+
+def default_model(adapter: str) -> str:
+    return _REGISTRY.get(adapter, {}).get("default_model", "unknown")
+
+
+def available_models(adapter: str) -> list[str]:
+    return _REGISTRY.get(adapter, {}).get("models", [])

axor_cli/auth.py

@@ -0,0 +1,189 @@
+from __future__ import annotations
+
+"""
+API key management for axor-cli.
+
+Priority order (highest to lowest):
+    1. --api-key CLI flag          (one-off, never saved)
+    2. ADAPTER_API_KEY env var     (e.g. ANTHROPIC_API_KEY)
+    3. ~/.axor/config.toml         (persistent, 0600 permissions)
+    4. None → prompt via /auth
+
+~/.axor/config.toml format:
+    [claude]
+    api_key = "sk-ant-..."
+
+    [openai]
+    api_key = "sk-..."
+"""
+
+import os
+import stat
+import getpass
+from pathlib import Path
+from typing import Any
+
+try:
+    import tomllib                        # Python 3.11+
+except ImportError:
+    try:
+        import tomli as tomllib           # fallback
+    except ImportError:
+        tomllib = None                    # type: ignore
+
+CONFIG_DIR  = Path.home() / ".axor"
+CONFIG_FILE = CONFIG_DIR / "config.toml"
+
+# env var names per adapter
+_ENV_VARS = {
+    "claude": "ANTHROPIC_API_KEY",
+    "openai": "OPENAI_API_KEY",
+}
+
+
+def resolve_api_key(adapter: str, flag_key: str | None = None) -> str | None:
+    """
+    Resolve API key using priority chain.
+    Returns key string or None if not found.
+    """
+    # 1. CLI flag
+    if flag_key:
+        return flag_key
+
+    # 2. env var
+    env_var = _ENV_VARS.get(adapter)
+    if env_var:
+        key = os.environ.get(env_var)
+        if key:
+            return key
+
+    # 3. config file
+    key = load_from_config(adapter)
+    if key:
+        # also set in env so axor-claude/axor-openai can pick it up
+        if env_var:
+            os.environ[env_var] = key
+        return key
+
+    return None
+
+
+def load_from_config(adapter: str) -> str | None:
+    """Load API key from ~/.axor/config.toml."""
+    if not CONFIG_FILE.exists():
+        return None
+
+    if tomllib is None:
+        return None
+
+    try:
+        with open(CONFIG_FILE, "rb") as f:
+            config: dict[str, Any] = tomllib.load(f)
+        return config.get(adapter, {}).get("api_key")
+    except Exception:
+        return None
+
+
+def _write_config(data: dict[str, Any]) -> None:
+    """Write config dict to file atomically with 0600 permissions."""
+    import tempfile
+    lines = []
+    for section, values in data.items():
+        lines.append(f"[{section}]")
+        for key, val in values.items():
+            lines.append(f'{key} = "{val}"')
+        lines.append("")
+
+    # atomic write via temp file
+    fd, tmp = tempfile.mkstemp(dir=CONFIG_DIR, prefix=".axor_cfg_")
+    try:
+        with os.fdopen(fd, "w") as f:
+            f.write("\n".join(lines))
+        os.replace(tmp, CONFIG_FILE)
+        CONFIG_FILE.chmod(stat.S_IRUSR | stat.S_IWUSR)
+    except Exception:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+        raise
+
+
+def save_to_config(adapter: str, api_key: str) -> None:
+    """Save API key to ~/.axor/config.toml with 0600 permissions."""
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+
+    existing: dict[str, Any] = {}
+    if CONFIG_FILE.exists() and tomllib is not None:
+        try:
+            with open(CONFIG_FILE, "rb") as f:
+                existing = tomllib.load(f)
+        except Exception:
+            existing = {}
+
+    if adapter not in existing:
+        existing[adapter] = {}
+    existing[adapter]["api_key"] = api_key
+    _write_config(existing)
+
+
+def clear_from_config(adapter: str) -> bool:
+    """Remove adapter key from config. Returns True if key existed."""
+    if not CONFIG_FILE.exists() or tomllib is None:
+        return False
+
+    try:
+        with open(CONFIG_FILE, "rb") as f:
+            existing: dict[str, Any] = tomllib.load(f)
+    except Exception:
+        return False
+
+    if adapter not in existing:
+        return False
+
+    del existing[adapter]
+    _write_config(existing)
+    return True
+
+
+def prompt_and_save(adapter: str) -> str | None:
+    """
+    Interactively prompt for API key.
+    Offers to save to config file.
+    Returns the key or None if user cancelled.
+    """
+    env_var = _ENV_VARS.get(adapter, f"{adapter.upper()}_API_KEY")
+
+    print(f"\n  No API key found for '{adapter}'.")
+    print(f"  (checked: --api-key flag, {env_var} env var, {CONFIG_FILE})\n")
+
+    try:
+        key = getpass.getpass(f"  {adapter.capitalize()} API key (hidden): ").strip()
+    except (KeyboardInterrupt, EOFError):
+        print()
+        return None
+
+    if not key:
+        print("  No key entered.")
+        return None
+
+    # offer to save
+    try:
+        save = input("  Save to ~/.axor/config.toml for future sessions? [Y/n]: ").strip().lower()
+    except (KeyboardInterrupt, EOFError):
+        print()
+        save = "n"
+
+    if save in ("", "y", "yes"):
+        try:
+            save_to_config(adapter, key)
+            print(f"  ✓ Key saved to {CONFIG_FILE} (permissions: 600)")
+        except Exception as e:
+            print(f"  ✗ Could not save: {e}")
+    else:
+        print("  Key not saved — valid for this session only.")
+
+    # set in env for adapter to pick up
+    env_var_name = _ENV_VARS.get(adapter)
+    if env_var_name:
+        os.environ[env_var_name] = key
+
+    return key

axor_cli/display.py

@@ -0,0 +1,185 @@
+from __future__ import annotations
+
+"""
+Terminal display helpers for axor-cli.
+
+Handles:
+  - Streaming text output (print as chunks arrive)
+  - Status lines (policy, tokens, tools)
+  - Spinner for thinking state
+  - Colored output (degrades gracefully if no color support)
+"""
+
+import sys
+import os
+import time
+import threading
+
+
+# ── Color support ──────────────────────────────────────────────────────────────
+
+def _supports_color() -> bool:
+    if not hasattr(sys.stdout, "isatty") or not sys.stdout.isatty():
+        return False
+    return os.environ.get("TERM", "") != "dumb"
+
+_COLOR = _supports_color()
+
+def _c(code: str, text: str) -> str:
+    if not _COLOR:
+        return text
+    return f"\033[{code}m{text}\033[0m"
+
+def dim(text: str)   -> str: return _c("2", text)
+def bold(text: str)  -> str: return _c("1", text)
+def green(text: str) -> str: return _c("32", text)
+def yellow(text: str)-> str: return _c("33", text)
+def red(text: str)   -> str: return _c("31", text)
+def cyan(text: str)  -> str: return _c("36", text)
+def blue(text: str)  -> str: return _c("34", text)
+
+
+# ── Header ─────────────────────────────────────────────────────────────────────
+
+def print_header(adapter: str, model: str, version: str = "0.1.0") -> None:
+    print()
+    print(bold(f"axor") + f" v{version} " +
+          dim("│") + f" adapter: {cyan(adapter)} " +
+          dim("│") + f" model: {dim(model)}")
+    print(dim("Type a task, a /command, or 'exit' to quit."))
+    print(dim("  /auth        — set API key"))
+    print(dim("  /cost        — token usage"))
+    print(dim("  /policy      — last execution policy"))
+    print(dim("  /compact     — compress context"))
+    print(dim("  /status      — session overview"))
+    print(dim("  /help        — all commands"))
+    print()
+
+
+# ── Spinner ────────────────────────────────────────────────────────────────────
+
+class Spinner:
+    """
+    Non-blocking spinner for "thinking" state.
+    Shows while waiting for first stream token.
+    Cleared as soon as text starts arriving.
+    """
+
+    _FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]
+
+    def __init__(self, prefix: str = "") -> None:
+        self._prefix  = prefix
+        self._running = False
+        self._thread: threading.Thread | None = None
+
+    def start(self) -> None:
+        if not _COLOR:
+            sys.stdout.write(dim("thinking...\n"))
+            sys.stdout.flush()
+            return
+        self._running = True
+        self._thread  = threading.Thread(target=self._spin, daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        self._running = False
+        if self._thread:
+            self._thread.join(timeout=0.5)
+        if _COLOR:
+            sys.stdout.write("\r\033[K")   # clear spinner line
+            sys.stdout.flush()
+
+    def _spin(self) -> None:
+        i = 0
+        while self._running:
+            frame = self._FRAMES[i % len(self._FRAMES)]
+            sys.stdout.write(f"\r{dim(self._prefix)}{dim(frame)} ")
+            sys.stdout.flush()
+            time.sleep(0.08)
+            i += 1
+
+
+# ── Streaming output ───────────────────────────────────────────────────────────
+
+def stream_text(text: str) -> None:
+    """Print a text chunk as it arrives from the stream."""
+    sys.stdout.write(text)
+    sys.stdout.flush()
+
+
+def print_tool_call(tool: str, args: dict, approved: bool) -> None:
+    if approved:
+        args_str = _format_args(args)
+        print(f"\n{dim('  ↳')} {yellow(tool)}{dim('('+ args_str +')')}", end="")
+    else:
+        print(f"\n{dim('  ✗')} {red(tool)} {dim('(denied)')}", end="")
+
+
+def print_tool_result(tool: str, result: str, approved: bool) -> None:
+    if approved:
+        preview = result[:60].replace("\n", " ").strip()
+        ellipsis = "…" if len(result) > 60 else ""
+        print(f" {dim('→')} {dim(preview + ellipsis)}", end="")
+
+
+def end_stream() -> None:
+    """Called after all stream events."""
+    print()   # final newline
+
+
+# ── Status after completion ────────────────────────────────────────────────────
+
+def print_completion(
+    policy: str,
+    input_tokens: int,
+    output_tokens: int,
+    cancelled: bool = False,
+) -> None:
+    total = input_tokens + output_tokens
+    if cancelled:
+        status = red("cancelled")
+    else:
+        status = green("✓ done")
+
+    print(
+        f"\n{dim('  ')}{status} "
+        f"{dim('│')} policy: {dim(policy)} "
+        f"{dim('│')} tokens: {dim(str(total))} "
+        f"{dim(f'(in: {input_tokens} out: {output_tokens})')}"
+    )
+
+
+def print_error(msg: str) -> None:
+    print(f"\n{red('  ✗')} {msg}")
+
+
+def print_info(msg: str) -> None:
+    print(f"\n{dim('  →')} {msg}")
+
+
+def print_success(msg: str) -> None:
+    print(f"\n{green('  ✓')} {msg}")
+
+
+# ── Prompt ─────────────────────────────────────────────────────────────────────
+
+def prompt(prefix: str = "> ") -> str:
+    """Read user input. Returns stripped string."""
+    try:
+        return input(bold(prefix)).strip()
+    except (KeyboardInterrupt, EOFError):
+        return "exit"
+
+
+# ── Helpers ────────────────────────────────────────────────────────────────────
+
+def _format_args(args: dict) -> str:
+    if not args:
+        return ""
+    parts = []
+    for k, v in list(args.items())[:2]:   # show max 2 args
+        val = str(v)[:30]
+        parts.append(f"{k}={val!r}")
+    if len(args) > 2:
+        parts.append("…")
+    return ", ".join(parts)

axor_cli/main.py

@@ -0,0 +1,314 @@
+from __future__ import annotations
+
+"""
+axor CLI — governed agent sessions from the terminal.
+
+Usage:
+    axor claude                         # interactive REPL
+    axor claude "refactor auth module"  # single task and exit
+    axor claude --policy readonly       # with preset policy
+    axor claude --limit 100000          # with soft token limit
+    axor claude --model claude-opus-4-5 # specific model
+    axor --list-adapters                # show available adapters
+"""
+
+import argparse
+import asyncio
+import os
+import sys
+
+# ensure axor-core is importable when running from source
+_here = os.path.dirname(os.path.abspath(__file__))
+for _candidate in [
+    os.path.join(_here, "..", "..", "axor-core"),
+    os.path.join(_here, "..", "..", "..", "axor-core"),
+]:
+    if os.path.isdir(os.path.join(_candidate, "axor_core")):
+        sys.path.insert(0, os.path.abspath(_candidate))
+        break
+
+from axor_cli import display, auth, adapters, streaming
+from axor_cli._version import __version__
+
+
+# ── Built-in REPL commands ─────────────────────────────────────────────────────
+
+_HELP = """
+Built-in commands:
+  /auth              Set or update API key (saved to ~/.axor/config.toml)
+  /auth --clear      Remove saved API key
+  /auth --show       Show where key is loaded from (never shows the key)
+  /cost              Token usage for this session
+  /policy            Last execution policy
+  /compact           Compress context (reduces token usage)
+  /status            Session overview
+  /model <name>      Switch model (adapter must support it)
+  /tools             Show tools available to current policy
+  /help              This message
+  exit / quit / ^D   Exit axor
+""".strip()
+
+
+def _parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="axor",
+        description="Governed agent sessions — powered by axor-core",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog=__doc__,
+    )
+
+    parser.add_argument(
+        "adapter",
+        nargs="?",
+        choices=adapters.list_adapters(),
+        metavar="ADAPTER",
+        help=f"Adapter to use: {', '.join(adapters.list_adapters())}",
+    )
+    parser.add_argument(
+        "task",
+        nargs="?",
+        help="Single task to run (skips REPL)",
+    )
+    parser.add_argument(
+        "--policy", "-p",
+        choices=["readonly", "sandboxed", "standard", "federated"],
+        help="Override policy (skips automatic selection)",
+    )
+    parser.add_argument(
+        "--limit", "-l",
+        type=int,
+        metavar="TOKENS",
+        help="Soft token limit for budget optimization",
+    )
+    parser.add_argument(
+        "--model", "-m",
+        help="Model to use (default: adapter's default)",
+    )
+    parser.add_argument(
+        "--api-key",
+        help="API key (not saved — use /auth for persistent keys)",
+    )
+    parser.add_argument(
+        "--no-skills",
+        action="store_true",
+        help="Skip loading CLAUDE.md and .claude/skills/",
+    )
+    parser.add_argument(
+        "--no-plugins",
+        action="store_true",
+        help="Skip loading .claude/plugins/",
+    )
+    parser.add_argument(
+        "--tools",
+        nargs="+",
+        default=["read", "write", "bash", "search", "glob"],
+        metavar="TOOL",
+        help="Tools to enable (default: read write bash search glob)",
+    )
+    parser.add_argument(
+        "--list-adapters",
+        action="store_true",
+        help="List available adapters and exit",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"axor {__version__}",
+    )
+
+    return parser.parse_args()
+
+
+# ── REPL loop ──────────────────────────────────────────────────────────────────
+
+async def repl(session, adapter: str, args: argparse.Namespace) -> None:
+    """Interactive REPL loop."""
+    policy_override = None
+    if args.policy:
+        from axor_core import presets
+        policy_override = presets.get(args.policy)
+
+    while True:
+        try:
+            line = display.prompt("> ")
+        except (EOFError, KeyboardInterrupt):
+            print()
+            display.print_info("Bye.")
+            break
+
+        if not line:
+            continue
+
+        if line.lower() in ("exit", "quit", "q"):
+            display.print_info("Bye.")
+            break
+
+        # ── /auth ──────────────────────────────────────────────────────────────
+        if line.startswith("/auth"):
+            parts = line.split()
+            if "--clear" in parts:
+                removed = auth.clear_from_config(adapter)
+                if removed:
+                    display.print_success(f"Key removed from ~/.axor/config.toml")
+                else:
+                    display.print_info("No key found in config.")
+
+            elif "--show" in parts:
+                env_var = {"claude": "ANTHROPIC_API_KEY", "openai": "OPENAI_API_KEY"}.get(adapter, "")
+                sources = []
+                if args.api_key:
+                    sources.append("--api-key flag (this session only)")
+                if env_var and os.environ.get(env_var):
+                    sources.append(f"{env_var} env var")
+                from axor_cli.auth import CONFIG_FILE
+                if auth.load_from_config(adapter):
+                    sources.append(f"~/.axor/config.toml")
+                if sources:
+                    display.print_info(f"Key loaded from: {', '.join(sources)}")
+                else:
+                    display.print_info("No key found. Run /auth to set one.")
+
+            else:
+                key = auth.prompt_and_save(adapter)
+                if key:
+                    # rebuild session with new key
+                    display.print_success("Key set. Rebuilding session...")
+                    try:
+                        new_session = adapters.build_session(
+                            adapter=adapter,
+                            api_key=key,
+                            model=args.model,
+                            tools=tuple(args.tools),
+                            soft_token_limit=args.limit,
+                            load_skills=not args.no_skills,
+                            load_plugins=not args.no_plugins,
+                        )
+                        session = new_session
+                        display.print_success("Session ready.")
+                    except Exception as e:
+                        display.print_error(f"Could not rebuild session: {e}")
+            continue
+
+        # ── /help ──────────────────────────────────────────────────────────────
+        if line in ("/help", "/?"):
+            print(f"\n{_HELP}\n")
+            continue
+
+        # ── /model ─────────────────────────────────────────────────────────────
+        if line.startswith("/model"):
+            parts = line.split(maxsplit=1)
+            if len(parts) < 2:
+                models = adapters.available_models(adapter)
+                display.print_info(f"Available models: {', '.join(models)}")
+            else:
+                display.print_info(f"Model switching requires session restart. "
+                                   f"Restart with: axor {adapter} --model {parts[1]}")
+            continue
+
+        # ── Governed slash commands (forwarded to session) ─────────────────────
+        if line.startswith("/"):
+            result = await session.run(line)
+            output = result.output
+            if output and output != "[cancelled]":
+                cmd_class = result.metadata.get("class", "passthrough")
+                if cmd_class == "governance":
+                    # structured response from envelope/trace — prefix with →
+                    display.print_info(output)
+                else:
+                    # context commands and passthrough — plain output
+                    print(f"\n{output}")
+            continue
+
+        # ── Task ───────────────────────────────────────────────────────────────
+        await streaming.run_task(session, line, policy=policy_override)
+
+
+# ── Main ───────────────────────────────────────────────────────────────────────
+
+async def async_main() -> int:
+    args = _parse_args()
+
+    # --list-adapters
+    if args.list_adapters:
+        print("\nAvailable adapters:")
+        for name in adapters.list_adapters():
+            available = adapters.is_available(name)
+            status = display.green("installed") if available else display.red("not installed")
+            hint = "" if available else f"  →  {adapters.get_install_hint(name)}"
+            print(f"  {name:12} {status}{hint}")
+        print()
+        return 0
+
+    # adapter required after this point
+    if not args.adapter:
+        print("Usage: axor <adapter> [task]")
+        print("       axor --list-adapters")
+        print(f"\nAvailable adapters: {', '.join(adapters.list_adapters())}")
+        return 1
+
+    adapter = args.adapter
+
+    # check adapter installed
+    if not adapters.is_available(adapter):
+        display.print_error(
+            f"Adapter '{adapter}' is not installed.\n"
+            f"  Install with: {adapters.get_install_hint(adapter)}"
+        )
+        return 1
+
+    # resolve API key
+    api_key = auth.resolve_api_key(adapter, flag_key=args.api_key)
+    if not api_key:
+        api_key = auth.prompt_and_save(adapter)
+        if not api_key:
+            display.print_error("No API key. Exiting.")
+            return 1
+
+    # build session
+    try:
+        session = adapters.build_session(
+            adapter=adapter,
+            api_key=api_key,
+            model=args.model,
+            tools=tuple(args.tools),
+            soft_token_limit=args.limit,
+            load_skills=not args.no_skills,
+            load_plugins=not args.no_plugins,
+        )
+    except Exception as e:
+        display.print_error(f"Could not start session: {e}")
+        return 1
+
+    policy_override = None
+    if args.policy:
+        from axor_core import presets
+        try:
+            policy_override = presets.get(args.policy)
+        except KeyError as e:
+            display.print_error(str(e))
+            return 1
+
+    # single task mode
+    if args.task:
+        await streaming.run_task(session, args.task, policy=policy_override)
+        return 0
+
+    # interactive REPL
+    model = args.model or adapters.default_model(adapter)
+    display.print_header(adapter=adapter, model=model, version=__version__)
+    await repl(session, adapter=adapter, args=args)
+    return 0
+
+
+def main() -> None:
+    """Entry point registered in pyproject.toml."""
+    try:
+        code = asyncio.run(async_main())
+        sys.exit(code)
+    except KeyboardInterrupt:
+        print()
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

axor_cli/streaming.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+"""
+Streaming execution driver for axor-cli.
+
+Connects GovernedSession to the terminal:
+  - shows spinner while waiting for first token
+  - prints text chunks as they arrive via set_text_callback()
+  - falls back to full output for non-streaming adapters
+  - prints completion stats
+"""
+
+import asyncio
+from typing import Any
+
+from axor_core import GovernedSession
+from axor_core.contracts.policy import ExecutionPolicy
+
+from axor_cli import display
+
+
+async def run_task(
+    session: GovernedSession,
+    task: str,
+    policy: ExecutionPolicy | None = None,
+) -> dict[str, Any]:
+    """
+    Run a task and stream output to terminal.
+
+    Returns execution summary:
+        {policy, input_tokens, output_tokens, cancelled, error}
+    """
+    spinner = display.Spinner(prefix="  ")
+    spinner.start()
+
+    summary: dict[str, Any] = {
+        "policy":        "unknown",
+        "input_tokens":  0,
+        "output_tokens": 0,
+        "cancelled":     False,
+        "error":         None,
+    }
+
+    try:
+        await _stream_run(session, task, policy, spinner, summary)
+    except asyncio.CancelledError:
+        spinner.stop()
+        summary["cancelled"] = True
+        display.print_completion(
+            policy=summary["policy"],
+            input_tokens=summary["input_tokens"],
+            output_tokens=summary["output_tokens"],
+            cancelled=True,
+        )
+    except Exception as e:
+        spinner.stop()
+        display.print_error(str(e))
+        summary["error"] = str(e)
+
+    return summary
+
+
+async def _stream_run(
+    session: GovernedSession,
+    task: str,
+    policy: ExecutionPolicy | None,
+    spinner: display.Spinner,
+    summary: dict[str, Any],
+) -> None:
+    text_received = False
+    executor = session._executor
+
+    # streaming path — adapter exposes set_text_callback()
+    if hasattr(executor, "set_text_callback"):
+        def on_text(chunk: str) -> None:
+            nonlocal text_received
+            if not text_received:
+                spinner.stop()
+                print()          # newline between prompt and output
+                text_received = True
+            display.stream_text(chunk)
+
+        executor.set_text_callback(on_text)
+
+    result = await session.run(task, policy=policy)
+
+    # ensure spinner stopped even on error/empty output
+    spinner.stop()
+
+    if not text_received:
+        # non-streaming adapter — print result all at once
+        if result.output and result.output != "[cancelled]":
+            print()
+            print(result.output)
+
+    display.end_stream()
+
+    summary["policy"]        = result.metadata.get("policy", "unknown")
+    summary["input_tokens"]  = result.token_usage.input_tokens
+    summary["output_tokens"] = result.token_usage.output_tokens
+    summary["cancelled"]     = result.metadata.get("cancelled", False)
+
+    display.print_completion(
+        policy=summary["policy"],
+        input_tokens=summary["input_tokens"],
+        output_tokens=summary["output_tokens"],
+        cancelled=summary["cancelled"],
+    )

axor_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,275 @@
+Metadata-Version: 2.4
+Name: axor-cli
+Version: 0.1.0
+Summary: CLI for axor-core governance kernel — governed agent sessions in your terminal
+Project-URL: Bug Tracker, https://github.com/Bucha11/axor-cli/issues
+Project-URL: Changelog, https://github.com/Bucha11/axor-cli/releases
+Project-URL: Repository, https://github.com/Bucha11/axor-cli
+License: MIT
+License-File: LICENSE
+Keywords: agents,axor,claude,cli,governance,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Terminals
+Requires-Python: >=3.11
+Requires-Dist: axor-core>=0.1.0
+Provides-Extra: all
+Requires-Dist: axor-claude>=0.1.0; extra == 'all'
+Requires-Dist: axor-openai>=0.1.0; extra == 'all'
+Provides-Extra: claude
+Requires-Dist: axor-claude>=0.1.0; extra == 'claude'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: openai
+Requires-Dist: axor-openai>=0.1.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# axor-cli
+
+[![CI](https://github.com/Bucha11/axor-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/Bucha11/axor-cli/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/axor-cli)](https://pypi.org/project/axor-cli/)
+[![Python](https://img.shields.io/pypi/pyversions/axor-cli)](https://pypi.org/project/axor-cli/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+
+**Governed agent sessions in your terminal.**
+
+Run Claude (or other LLMs) under axor-core governance — controlled context, explicit tool permissions, token optimization, and full audit trail.
+
+---
+
+## Installation
+
+```bash
+# CLI + Claude adapter
+pip install axor-cli[claude]
+
+# or step by step
+pip install axor-cli
+pip install axor-claude
+```
+
+---
+
+## Quick Start
+
+```bash
+# Interactive REPL
+axor claude
+
+# Single task and exit
+axor claude "refactor the auth module"
+
+# With options
+axor claude --policy readonly "review this PR for security issues"
+axor claude --limit 100000 "migrate the entire codebase to Go"
+axor claude --model claude-opus-4-5 "design the new architecture"
+```
+
+---
+
+## Authentication
+
+On first run, axor asks for your API key and saves it to `~/.axor/config.toml` (permissions: 600):
+
+```
+$ axor claude
+
+  No API key found for 'claude'.
+  (checked: --api-key flag, ANTHROPIC_API_KEY env var, ~/.axor/config.toml)
+
+  Anthropic API key (hidden): ****
+  Save to ~/.axor/config.toml for future sessions? [Y/n]: y
+  ✓ Key saved to ~/.axor/config.toml (permissions: 600)
+```
+
+Key priority (highest to lowest):
+
+| Source | When used |
+|--------|-----------|
+| `--api-key` flag | One-off override, never saved |
+| `ANTHROPIC_API_KEY` env var | CI/CD, containers |
+| `~/.axor/config.toml` | Persistent, set via `/auth` |
+
+Manage saved keys with `/auth` in the REPL:
+
+```
+> /auth              # set or update key (prompts, then saves)
+> /auth --show       # show where key is loaded from (never shows the key)
+> /auth --clear      # remove saved key
+```
+
+---
+
+## Interactive REPL
+
+```
+$ axor claude
+axor v0.1.0 │ adapter: claude │ model: claude-sonnet-4-5
+Type a task, a /command, or 'exit' to quit.
+
+> refactor the auth module to add rate limiting
+  ↳ read(path='auth.py') → def authenticate(token):…
+  ↳ write(path='auth.py') → …
+✓ done │ policy: moderate_mutative │ tokens: 1,247 (in: 800 out: 447)
+
+> /cost
+  → Tokens spent this session: 1,247
+
+> /compact
+  → Context compaction requested — will apply on next execution.
+
+> exit
+  → Bye.
+```
+
+### REPL commands
+
+| Command | Class | Description |
+|---------|-------|-------------|
+| `/auth` | built-in | Set or update API key |
+| `/auth --clear` | built-in | Remove saved key |
+| `/auth --show` | built-in | Show key source (never the key itself) |
+| `/model` | built-in | List available models |
+| `/help` | built-in | All commands |
+| `/cost` | governed | Token usage for this session |
+| `/policy` | governed | Last execution policy |
+| `/compact` | governed | Compress context |
+| `/status` | governed | Session overview |
+| `/tools` | governed | Tools available to current policy |
+| `exit` / `quit` / `^D` | — | Exit |
+
+Governed commands (`/cost`, `/policy`, etc.) are handled by axor-core — they never reach the executor.
+
+---
+
+## CLI options
+
+```
+axor <adapter> [task] [options]
+
+Arguments:
+  adapter           Adapter: claude, openai
+  task              Single task — runs and exits (skips REPL)
+
+Options:
+  -p, --policy      Preset: readonly, sandboxed, standard, federated
+  -l, --limit       Soft token limit (budget optimization signals)
+  -m, --model       Model override (e.g. claude-opus-4-5)
+  --api-key         API key for this session (never saved)
+  --tools           Tools to enable (default: read write bash search glob)
+  --no-skills       Skip CLAUDE.md and .claude/skills/
+  --no-plugins      Skip .claude/plugins/
+  --list-adapters   Show installed adapters and exit
+  --version         Show version
+```
+
+---
+
+## Examples
+
+```bash
+# Analysis only — no writes, no bash
+axor claude --policy readonly "find all security issues in auth.py"
+
+# Specific tools only
+axor claude --tools read search "find all TODO comments"
+
+# Large migration with budget
+axor claude --limit 200000 "rewrite the API layer to use async/await"
+
+# Specific model
+axor claude --model claude-opus-4-5 "design the new microservices architecture"
+
+# No extension loading (faster startup)
+axor claude --no-skills --no-plugins "quick question"
+
+# CI — reads key from env, single task, exits
+ANTHROPIC_API_KEY=sk-ant-... axor claude "run code review"
+```
+
+---
+
+## Adapters
+
+```bash
+axor --list-adapters
+
+Available adapters:
+  claude       installed
+  openai       not installed  →  pip install axor-openai
+```
+
+Each adapter package must expose `make_session(**kwargs) -> GovernedSession`.
+
+---
+
+## Streaming output
+
+When an adapter supports streaming (e.g. `axor-claude`), text is printed to the terminal as it arrives — no waiting for the full response. A spinner shows while Claude is thinking.
+
+Non-streaming adapters print the full output when execution completes.
+
+---
+
+## Config file
+
+`~/.axor/config.toml` — auto-created with `chmod 600`:
+
+```toml
+[claude]
+api_key = "sk-ant-..."
+
+[openai]
+api_key = "sk-..."
+```
+
+---
+
+## Repository structure
+
+```
+axor-cli/
+├── axor_cli/
+│   ├── main.py        CLI entrypoint, REPL loop, argument parsing
+│   ├── auth.py        Key management — ~/.axor/config.toml, priority chain
+│   ├── adapters.py    Adapter registry, lazy imports, build_session()
+│   ├── display.py     Terminal formatting — color, spinner, streaming output
+│   ├── streaming.py   Connects GovernedSession to terminal display
+│   └── _version.py
+└── tests/
+    ├── conftest.py         tmp_home fixture, anthropic mock
+    └── unit/
+        ├── test_auth.py        11 tests — config file, permissions, priority
+        ├── test_adapters.py     8 tests — registry, availability, session build
+        ├── test_display.py      display formatting
+        └── test_streaming.py   11 tests — output, callback, error, policy override
+```
+
+---
+
+## Running tests
+
+```bash
+pytest tests/unit/   # no API key needed, anthropic SDK mocked
+```
+
+---
+
+## Requirements
+
+- Python 3.11+
+- `axor-core >= 0.1.0`
+- At least one adapter: `axor-claude` or `axor-openai`
+
+---
+
+## License
+
+MIT

axor_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+axor_cli/__init__.py,sha256=h1bnQ-G2v-SAcBO-iMJtfTj3EEmT4t7oeueLMyK8NSI,130
+axor_cli/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+axor_cli/adapters.py,sha256=yw17XEGBV8BFXDmtR3E1Nikf7uIXXROjFpz8mHlo4OQ,3624
+axor_cli/auth.py,sha256=KgCkoNHUm9MMooTKVBIjJR7LN1qOP6mXDYUaiDhlIEc,5015
+axor_cli/display.py,sha256=Z_Dk3as7ZmgbusWepLFnv-0BaBrIzPk-dgWLY4SI0jk,6363
+axor_cli/main.py,sha256=V6JvMy_f01EoMYvdC-UbumOpwKAWCf_rGTZQpQAWo60,11621
+axor_cli/streaming.py,sha256=f3Bv7s7Q8DCE-XkK8LjpjvdO0iE2ublUqqojiRgg3Pw,3063
+axor_cli-0.1.0.dist-info/METADATA,sha256=0bP5HfSgVtd2TSiS0FkRqfViWPBU1nMJKst4clUFYOk,7683
+axor_cli-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+axor_cli-0.1.0.dist-info/entry_points.txt,sha256=DjI2w3zZ_HEFctGqpzADUYTcxvYO2CvQfh5emVIjXP8,44
+axor_cli-0.1.0.dist-info/licenses/LICENSE,sha256=u1tea2uwiiU3VXz7AOfI5nBAW5-Oxbd6WmE3f-00qYQ,1074
+axor_cli-0.1.0.dist-info/RECORD,,

axor_cli-0.1.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_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+axor = axor_cli.main:main

axor_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Axor Contributors
+
+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.