kyvvu-cli 1.0.0__py3-none-any.whl

kyvvu_cli/__init__.py

@@ -0,0 +1,4 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Kyvvu B.V.
+
+"""Kyvvu CLI — command-line interface for the Kyvvu SDK."""

kyvvu_cli/__main__.py

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Kyvvu B.V.
+
+"""Allow ``python -m kyvvu`` to invoke the CLI."""
+from kyvvu_cli.main import app
+
+app()

kyvvu_cli/__version__.py

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

kyvvu_cli/_build_info.json

@@ -0,0 +1,19 @@
+{
+  "commit": "c6dc2dcb8d96d4842ed989267301bfdcb3cfa139",
+  "versions": {
+    "API_VERSION": "1.0.0",
+    "BASELINE_VERSION": "1.0.0",
+    "CLAUDE_VERSION": "1.0.0",
+    "CLI_VERSION": "1.0.0",
+    "CREWAI_VERSION": "1.0.0",
+    "ENGINE_VERSION": "1.0.0",
+    "LANGCHAIN_VERSION": "1.0.0",
+    "MIN_ENGINE_VERSION": "0.13.0",
+    "MIN_POLICY_SCHEMA": "1",
+    "NEXT_MIN_ENGINE_DATE": "",
+    "NEXT_MIN_ENGINE_VERSION": "",
+    "SDK_VERSION": "1.0.0",
+    "TEMPLATES_VERSION": "1.0.0",
+    "WEB_VERSION": "1.0.0"
+  }
+}

kyvvu_cli/agents.py

@@ -0,0 +1,130 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Kyvvu B.V.
+
+"""Agent inspection command: list-agents, and agent key -> id resolution."""
+from __future__ import annotations
+
+import re
+from typing import Any, Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from kyvvu_cli.client import api_get, require_cli_pat
+from kyvvu_cli.config import get_api_url
+
+console = Console()
+
+# The platform's agent ids: ``agent_`` plus hex (``agents/service.py``).
+_AGENT_ID_RE = re.compile(r"agent_[0-9a-f]+")
+
+
+def _fetch_agents(
+    api_key: str,
+    api_url: str,
+    *,
+    environment: Optional[str] = None,
+    include_inactive: bool = False,
+) -> list[Any]:
+    """Return the workspace's agents from ``GET /api/v1/agents``.
+
+    The platform filters out deactivated agents unless ``include_inactive=true``
+    is sent, so the filtering is the server's, not ours (#807).
+    """
+    params: dict[str, str] = {"limit": "1000"}
+    if environment:
+        params["environment"] = environment
+    if include_inactive:
+        params["include_inactive"] = "true"
+    agents = api_get("/api/v1/agents", params=params, api_key=api_key, api_url=api_url)
+    if isinstance(agents, dict) and "items" in agents:
+        agents = agents["items"]
+    if not isinstance(agents, list):
+        agents = [agents] if agents else []
+    return agents
+
+
+def resolve_agent_id(value: str, *, api_key: str, api_url: str) -> str:
+    """Return the platform ``agent_id`` for *value*, an agent id or an agent key.
+
+    ``--agent-id`` used to take only the platform-assigned ``agent_...`` id,
+    and a key was answered with ``404 Agent not found`` (#795). A value shaped
+    like an id is passed through untouched; anything else is looked up among
+    the workspace's active agents by ``agent_key``, in the one list call
+    ``list-agents`` makes.
+
+    Args:
+        value: What the user passed to ``--agent-id``.
+        api_key: The CLI PAT.
+        api_url: The platform URL.
+
+    Returns:
+        The agent's ``agent_id``.
+
+    Raises:
+        typer.Exit: With status 1 when no agent, or more than one, has that key.
+    """
+    if _AGENT_ID_RE.fullmatch(value):
+        return value
+    matches = [
+        a for a in _fetch_agents(api_key, api_url)
+        if a.get("agent_key") == value
+    ]
+    ids = [str(a.get("agent_id", a.get("id", ""))) for a in matches]
+    if len(ids) == 1:
+        return ids[0]
+    if not ids:
+        typer.echo(
+            f"No active agent with id or key '{value}' in this workspace. "
+            "Run `kyvvu list-agents` to see them.",
+            err=True,
+        )
+    else:
+        typer.echo(
+            f"More than one agent has the key '{value}' ({', '.join(ids)}). "
+            "Pass the agent id instead.",
+            err=True,
+        )
+    raise typer.Exit(1)
+
+
+def list_agents(
+    environment: Optional[str] = None,
+    include_inactive: bool = False,
+) -> None:
+    """List registered agents.
+
+    Args:
+        environment: Only agents in this environment.
+        include_inactive: Also list deactivated agents. Sent to the platform
+            as ``include_inactive=true``; it never returns them otherwise.
+    """
+    api_key = require_cli_pat()
+    api_url = get_api_url()
+
+    agents = _fetch_agents(
+        api_key, api_url, environment=environment, include_inactive=include_inactive
+    )
+
+    if not agents:
+        typer.echo("No agents found.")
+        return
+
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("AGENT_KEY")
+    table.add_column("AGENT_ID")
+    table.add_column("NAME")
+    table.add_column("ENVIRONMENT")
+    table.add_column("ACTIVE")
+
+    for a in agents:
+        table.add_row(
+            a.get("agent_key", ""),
+            a.get("agent_id", a.get("id", "")),
+            a.get("name", ""),
+            a.get("environment", ""),
+            "\u2713" if a.get("active", True) else "\u2717",
+        )
+
+    console.print(table)

kyvvu_cli/auth.py

@@ -0,0 +1,314 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Kyvvu B.V.
+
+"""Authentication commands: auth, logout, whoami."""
+
+from __future__ import annotations
+
+import os
+import socket
+import sys
+import threading
+import time
+import webbrowser
+from typing import Optional
+
+import typer
+
+import httpx
+
+from kyvvu_cli.client import api_delete, api_get, api_post, require_cli_pat
+from kyvvu_cli.config import (
+    clear_cli_auth,
+    get_api_url,
+    get_cli_auth,
+    save_cli_auth,
+)
+
+
+def _print_waiting_message(email: str) -> None:
+    """Explain the ONE remaining reason an account cannot act yet.
+
+    This used to say an administrator at your organisation had to approve
+    you, which was true while an email domain founded or joined an
+    organisation and everyone after the first person queued. Nothing arrives
+    unapproved now; the registration cap is what is left, it is a property of
+    the PLATFORM rather than of anybody's organisation, and only Kyvvu staff
+    can release it. Telling somebody to ask their administrator would send
+    them to a person who cannot help.
+    """
+    typer.echo(
+        f"\n{email} is waiting to be admitted.\n"
+        f"Kyvvu is at its registration limit, so new accounts are released by "
+        f"Kyvvu rather than by anyone at your organization.\n"
+        f"Run `kyvvu whoami` to check."
+    )
+
+
+def _device_label(device_label: Optional[str]) -> str:
+    if device_label:
+        return device_label
+    try:
+        hostname = socket.gethostname()
+    except Exception:
+        hostname = ""
+    return hostname or "CLI"
+
+
+def _open_browser(url: str) -> None:
+    # Run off the main thread: webbrowser.open() is not guaranteed to
+    # return immediately (some configured browsers, e.g. text-mode ones,
+    # run synchronously until the user exits them), and blocking here would
+    # delay entering the polling loop below.
+    try:
+        webbrowser.open(url)
+    except Exception:  # noqa: S110 - best effort operation must not affect the primary result
+        pass
+
+
+def auth(api_url: Optional[str] = None, device_label: Optional[str] = None) -> None:
+    """Log in via the device-code flow: print a code, wait for browser approval."""
+    url = api_url or get_api_url()
+
+    start = api_post(
+        "/api/v1/auth/cli/start",
+        json={"device_label": _device_label(device_label)},
+        api_url=url,
+    )
+
+    device_code = start["device_code"]
+    user_code = start["user_code"]
+    verification_uri_complete = start["verification_uri_complete"]
+    interval = int(start.get("interval", 5))
+    expires_in = int(start.get("expires_in", 900))
+
+    threading.Thread(
+        target=_open_browser, args=(verification_uri_complete,), daemon=True
+    ).start()
+
+    typer.echo("Opening your browser to approve this login...")
+    typer.echo(f"If it doesn't open, visit this URL manually: {verification_uri_complete}")
+    typer.echo(f"(Code: {user_code})")
+    typer.echo("")
+    typer.echo("Waiting for you to approve...")
+    sys.stdout.flush()
+
+    deadline = time.monotonic() + expires_in
+
+    while True:
+        if time.monotonic() >= deadline:
+            typer.echo("This code has expired. Run `kyvvu auth` again.", err=True)
+            raise typer.Exit(1)
+
+        time.sleep(interval)
+
+        try:
+            with httpx.Client(base_url=url, timeout=15.0) as client:
+                resp = client.post("/api/v1/auth/cli/token", json={"device_code": device_code})
+        except (httpx.ConnectError, httpx.TimeoutException):
+            typer.echo(f"Could not reach {url}. Check your network connection.", err=True)
+            raise typer.Exit(1)
+
+        if resp.status_code == 200:
+            data = resp.json()
+            access_token = data.get("access_token", "")
+            break
+
+        try:
+            error = resp.json().get("error")
+        except Exception:
+            error = None
+
+        if error == "authorization_pending":
+            continue
+        elif error == "slow_down":
+            # RFC 8628 §3.5: server is throttling us -- back off by 5s and
+            # keep polling instead of treating this as a fatal error.
+            interval += 5
+            continue
+        elif error == "access_denied":
+            typer.echo("Login was denied.", err=True)
+            raise typer.Exit(1)
+        elif error == "expired_token":
+            typer.echo("This code has expired. Run `kyvvu auth` again.", err=True)
+            raise typer.Exit(1)
+        else:
+            detail = error or resp.text
+            typer.echo(f"Login failed: {detail}", err=True)
+            raise typer.Exit(1)
+
+    save_cli_auth(api_key=access_token, api_url=url)
+
+    me = api_get("/api/v1/auth/me", api_key=access_token, api_url=url)
+    email = me.get("email", "unknown")
+    # `is_verified` is gone from /auth/me; it meant three things at once and
+    # was replaced by the two that survived. `is_capped` is the one that stops
+    # somebody signing in.
+    is_capped = bool(me.get("is_capped", False))
+
+    if not is_capped:
+        typer.echo(f"\n\u2713 Logged in as {email}")
+    else:
+        _print_waiting_message(email)
+        raise typer.Exit(0)
+
+
+def logout() -> None:
+    """Revoke and clear the stored CLI PAT; other config sections are kept."""
+    cli_auth = get_cli_auth()
+    api_key = cli_auth.get("api_key")
+    api_url = cli_auth.get("api_url") or get_api_url()
+
+    revoke_failed = False
+    if api_key:
+        try:
+            api_delete("/api/v1/auth/cli/session", api_key=api_key, api_url=api_url)
+        except typer.Exit:
+            revoke_failed = True
+
+    clear_cli_auth()
+
+    if revoke_failed:
+        typer.echo(
+            "Warning: could not reach the server to revoke your session; "
+            "cleared local credentials anyway.",
+            err=True,
+        )
+
+    typer.echo("\u2713 Logged out.")
+
+
+def _policy_source_line() -> str:
+    """Describe where an agent built from this shell's env would get policies.
+
+    ``whoami`` already answers "where do my logs go"; this answers the question
+    that actually decides whether an agent enforces anything. It reads the same
+    ``KV_*`` environment the SDK reads, so it reports the configuration a
+    ``python agent.py`` in this shell would resolve — not the CLI's own
+    credentials, which are stored separately.
+
+    Returns:
+        A one-line description, explicit about the case where nothing is
+        configured and an agent would therefore enforce nothing.
+    """
+    from kyvvu_engine import KyvvuSettings
+    from kyvvu_engine import PolicySourceKind
+
+    settings = KyvvuSettings()
+    kind = settings.policy_source_kind()
+    if kind is PolicySourceKind.api:
+        return f"{settings.api_url} (agent_key={settings.agent_key})"
+    if kind is PolicySourceKind.disk_cache:
+        return f"disk cache only: {settings.policy_cache_path}"
+    missing = ", ".join(settings.missing_policy_source_settings())
+    return f"\u2717 none — an agent here would enforce nothing (missing {missing})"
+
+
+def _log_location_line() -> str:
+    """Describe where an agent's steps go, without over-claiming.
+
+    ``whoami`` reads this shell's ``KV_*``; it cannot read the agent's source.
+    That matters because ``kyvvu init`` writes ``agent_key`` into ``agent.py``
+    and nothing into ``.env``, so the scaffold's own happy path has no
+    ``KV_AGENT_KEY`` here -- ``"auto"`` (#357) therefore resolves to ``stdout``
+    for this process while the very same project's ``python agent.py`` posts to
+    the platform.
+
+    Printing the bare resolved value reproduced, inverted, exactly the bug the
+    old ``os.environ.get("KV_LOG_LOCATION", "stdout")`` line caused: a
+    confident answer that is wrong for the documented case. So when the answer
+    depends on something only the agent supplies, say so.
+
+    Returns:
+        A one-line description, qualified when this shell cannot decide it.
+    """
+    from kyvvu_engine import AUTO_LOG_LOCATION, KyvvuSettings
+    from kyvvu_engine import PolicySourceKind
+
+    settings = KyvvuSettings()
+    resolved = settings.effective_log_location or "none (logging disabled)"
+    if settings.log_location != AUTO_LOG_LOCATION:
+        return resolved
+    if settings.policy_source_kind() is PolicySourceKind.api:
+        return f"{resolved} (auto)"
+    # The scaffold passes ``agent_key=`` in code and reads everything else
+    # (``KV_API_KEY``, ``KV_API_URL``) from the environment, so only a missing
+    # ``KV_AGENT_KEY`` is something it supplies itself (#797). Anything else
+    # missing here is missing for the scaffold too, and is named as a
+    # condition rather than claimed as supplied.
+    still_needed = " and ".join(
+        env_var
+        for env_var in (
+            part.split(" / ")[1] for part in settings.missing_policy_source_settings()
+        )
+        if env_var != "KV_AGENT_KEY"
+    )
+    condition = f", with {still_needed} set," if still_needed else ""
+    return (
+        f"{resolved} (auto — for THIS shell; the kyvvu init scaffold passes "
+        f"agent_key in code and{condition} resolves it to "
+        f"{_scaffold_api_url(settings.api_url)})"
+    )
+
+
+def _scaffold_api_url(shell_api_url: str) -> str:
+    """Name the URL a project ``kyvvu init`` scaffolds here would call.
+
+    The scaffold reads ``KV_API_URL`` from the environment, and an exported
+    value (or one in this directory's ``.env``) wins over anything in a file.
+    When nothing sets it, ``kyvvu init`` writes the URL this CLI is logged in
+    to into ``.env.example`` (#797), so the scaffold calls *that* rather than
+    the production default this shell would resolve. Saying production while
+    logged in to dev sent a reader to create a key in the wrong place (#816).
+
+    Args:
+        shell_api_url: The URL this shell's ``KyvvuSettings`` resolved.
+
+    Returns:
+        The URL, followed by where it comes from when that is the scaffold's
+        ``.env.example`` rather than this shell.
+    """
+    from kyvvu_cli.init_cmd import _logged_in_api_url
+
+    if os.environ.get("KV_API_URL"):
+        return shell_api_url
+    session_url = _logged_in_api_url()
+    if session_url is None:
+        return shell_api_url
+    return f"{session_url}, the KV_API_URL kyvvu init writes into .env.example"
+
+
+def whoami() -> None:
+    """Print current user info and endpoint configuration."""
+    api_key = require_cli_pat()
+    cli_auth = get_cli_auth()
+    api_url = cli_auth.get("api_url") or get_api_url()
+
+    me = api_get("/api/v1/auth/me", api_key=api_key, api_url=api_url)
+    email = me.get("email", "unknown")
+    is_capped = bool(me.get("is_capped", False))
+    is_suspended = bool(me.get("is_suspended", False))
+    if is_capped:
+        status = "\u2717 waiting to be admitted by Kyvvu"
+    elif is_suspended:
+        status = "\u2717 suspended in this workspace"
+    else:
+        status = "\u2713 active"
+
+    log_location = _log_location_line()
+    # Incidents follow the same location + format sink model as traces and
+    # default to the trace sink when KV_INCIDENT_LOCATION is unset (#225).
+    incident_location = os.environ.get("KV_INCIDENT_LOCATION")
+    if incident_location:
+        incident_display = incident_location
+    else:
+        # The log line above is already qualified when it needs to be;
+        # repeating its whole parenthetical here doubled it (#797).
+        incident_display = "(inherits log location)"
+
+    typer.echo(f"Email:         {email}")
+    typer.echo(f"API URL:       {api_url}")
+    typer.echo(f"Status:        {status}")
+    typer.echo(f"Log location:  {log_location}")
+    typer.echo(f"Incidents:     {incident_display}")
+    typer.echo(f"Policy source: {_policy_source_line()}")

kyvvu_cli/cli_plugins.py

@@ -0,0 +1,71 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright 2026 Kyvvu B.V.
+
+"""Installed extensions for the ``kyvvu`` command."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from functools import lru_cache
+from importlib.metadata import entry_points
+from typing import Callable, TYPE_CHECKING
+
+import typer
+
+if TYPE_CHECKING:
+    from kyvvu_cli.doctor import Check
+
+
+@dataclass(frozen=True)
+class CliPlugin:
+    """A validated CLI entry point and its optional diagnostics."""
+
+    name: str
+    app: typer.Typer
+    status: Callable[[], str] | None
+    doctor: Callable[[], Check] | None
+
+
+def warn(name: str, error: Exception) -> None:
+    """Report one failed plugin operation without interrupting the CLI."""
+    message = " ".join(str(error).splitlines())
+    typer.echo(f"Warning: CLI plugin {name}: {message}", err=True)
+
+
+@lru_cache(maxsize=1)
+def cli_plugins() -> tuple[CliPlugin, ...]:
+    """Load installed plugins once, isolating each distribution's import."""
+    plugins = []
+    for entry in entry_points(group="kyvvu.cli_plugins"):
+        try:
+            module = entry.load()
+            plugin_app = getattr(module, "app")
+            if not isinstance(plugin_app, typer.Typer):
+                raise TypeError("app must be a Typer instance")
+            status = getattr(module, "status", None)
+            doctor = getattr(module, "doctor", None)
+            if status is not None and not callable(status):
+                raise TypeError("status must be callable")
+            if doctor is not None and not callable(doctor):
+                raise TypeError("doctor must be callable")
+            plugins.append(CliPlugin(entry.name, plugin_app, status, doctor))
+        except Exception as exc:
+            warn(entry.name, exc)
+    return tuple(plugins)
+
+
+def doctor_checks() -> list[Check]:
+    """Run optional plugin checks while preserving the rest of the report."""
+    from kyvvu_cli.doctor import Check
+
+    checks = []
+    for plugin in cli_plugins():
+        if plugin.doctor is None:
+            continue
+        try:
+            check = plugin.doctor()
+            if not isinstance(check, Check):
+                raise TypeError("doctor must return a Check")
+            checks.append(check)
+        except Exception as exc:
+            warn(plugin.name, exc)
+    return checks