tetra-cli 0.2.0__py3-none-any.whl

tetra_cli/api_client/operations/webhooks.py

@@ -0,0 +1,50 @@
+"""Pure async operations for registering an API key's webhook."""
+import re
+from typing import Any
+
+from tetra_cli.api_client import TetraClient
+from tetra_cli.registry import arg, operation, opt
+
+# API-key UIDs are opaque tokens (UUID-style). Validate before interpolating
+# into the request path so a malformed/crafted value can't redirect the call
+# to a different endpoint (defense-in-depth path-injection guard).
+_UID_RE = re.compile(r"^[A-Za-z0-9_-]{1,128}$")
+
+
+def _require_uid(api_key_uid: str) -> str:
+    if not _UID_RE.fullmatch(api_key_uid or ""):
+        raise ValueError(f"Invalid api_key_uid: {api_key_uid!r}")
+    return api_key_uid
+
+
+@operation(
+    cli="api-keys set-webhook",
+    summary="Register the agent push webhook on an API key.",
+    covers=[("PATCH", "/api/v1/api-keys/{uid}")],
+    params={
+        "api_key_uid": arg(help="API key UID to attach the webhook to."),
+        "url": arg(help="HTTPS endpoint to POST new user messages to."),
+        "secret": opt("--secret", help="HMAC signing secret."),
+    },
+)
+async def set_webhook(
+    client: TetraClient, api_key_uid: str, *, url: str, secret: str | None = None
+) -> dict[str, Any]:
+    """Register (or update) the webhook URL+secret on an API key."""
+    _require_uid(api_key_uid)
+    body: dict[str, Any] = {"webhook_url": url}
+    if secret is not None:
+        body["webhook_secret"] = secret
+    return await client.patch(f"/api/v1/api-keys/{api_key_uid}", json=body)
+
+
+@operation(
+    cli="api-keys clear-webhook",
+    summary="Remove the agent push webhook from an API key.",
+    covers=[("PATCH", "/api/v1/api-keys/{uid}")],
+    params={"api_key_uid": arg(help="API key UID to clear the webhook from.")},
+)
+async def clear_webhook(client: TetraClient, api_key_uid: str) -> dict[str, Any]:
+    """Remove the webhook from an API key."""
+    _require_uid(api_key_uid)
+    return await client.patch(f"/api/v1/api-keys/{api_key_uid}", json={"webhook_url": None})

tetra_cli/api_client/operations/xp.py

@@ -0,0 +1,27 @@
+"""Pure async operations for the XP page API."""
+from typing import Any
+
+from tetra_cli.api_client import TetraClient
+from tetra_cli.registry import operation
+
+
+@operation(
+    cli="xp stats",
+    summary="Get XP page statistics: level, streak, multiplier, achievements, and rankings.",
+    covers=[("GET", "/api/v1/xp/stats")],
+)
+async def get_xp_stats(client: TetraClient) -> dict[str, Any]:
+    """Get XP page statistics for the current account.
+
+    Returns comprehensive XP data: current level and XP progress, streak and
+    multiplier, next reward preview, activity stats, recent achievements, and
+    value performance rankings. Takes no parameters — the backend scopes the
+    response to the authenticated account.
+
+    Args:
+        client: Authenticated TetraClient
+
+    Returns:
+        Dict with the full XP stats payload (XpStatsResponse).
+    """
+    return await client.get("/api/v1/xp/stats")

tetra_cli/cli/__init__.py

@@ -0,0 +1,5 @@
+"""Tetra command-line interface.
+
+Mirrors the MCP server's tool surface, emitting JSON to stdout. Auth via
+TETRA_API_KEY / TETRA_USERNAME env vars, identical to the MCP server.
+"""

tetra_cli/cli/__main__.py

@@ -0,0 +1,5 @@
+"""Entrypoint: python -m tetra_cli.cli"""
+from tetra_cli.cli.app import main
+
+if __name__ == "__main__":
+    main()

tetra_cli/cli/app.py

@@ -0,0 +1,86 @@
+"""Root Typer app with command group registration and the entrypoint."""
+import typer
+
+from tetra_cli.cli.output import set_pretty
+
+app = typer.Typer(
+    help=(
+        "Tetra CLI — JSON-emitting command line for the Tetra API. "
+        "After making changes, log them with 'tetra-cli conversations ai-action' so any AI shares the history."
+    ),
+    no_args_is_help=True,
+)
+
+
+def _pretty_callback(value: bool) -> bool:
+    set_pretty(value)
+    return value
+
+
+@app.callback()
+def root(
+    pretty: bool = typer.Option(
+        False, "--pretty", help="Indent JSON output for human reading.",
+        callback=_pretty_callback, is_eager=True,
+    ),
+) -> None:
+    """Tetra CLI — emits JSON to stdout, errors to stderr."""
+
+
+_commands_registered = False
+
+
+def register_commands() -> None:
+    """Mount per-noun subapps. Deferred to avoid circular imports at module load.
+
+    Idempotent: several test modules import the app and call this at module
+    load, so guard against re-mounting (which would raise Typer duplicate
+    command/group errors).
+
+    The ``goals`` and ``events`` groups are NOT registered manually — they are
+    produced by ``register_generated`` from the @operation registry, which is
+    now the single source of truth for those two groups.
+    """
+    global _commands_registered
+    if _commands_registered:
+        return
+    _commands_registered = True
+
+    from tetra_cli.cli.commands import auth, guide, messages, skill
+    from tetra_cli.cli.generate import register_generated
+
+    # Generated commands from the @operation registry are the SINGLE source of
+    # truth for every API-backed capability. Register them first; the returned
+    # set is the top-level groups they own (used only as a safety check below).
+    generated = register_generated(app)
+
+    # The only surviving hand-written modules are those with no single-return
+    # API mapping a generator can express:
+    #   * auth  — local API-key config (no API route at all)
+    #   * guide — static ontology text (no API route)
+    #   * messages — the SSE stream (`subscribe`) + poll loop (`watch`) only;
+    #     its read/post/reply/action commands are now generated `conversations`
+    #     ops. `messages` is NOT a generated group, so mounting it is safe.
+    assert "messages" not in generated, "messages must not be a generated group"
+    app.add_typer(
+        messages.app, name="messages",
+        help="Stream (subscribe) or poll (watch) the AI thread in real time.",
+    )
+
+    # auth and guide are local/static (no API op); always manual.
+    app.add_typer(auth.app, name="auth", help="Save / inspect / clear the API key.")
+    app.command(name="guide", help="Print the Tetra ontology guide (values/goals/events).")(guide.guide)
+
+    # skill — installs the bundled agent skill locally (no API op).
+    app.add_typer(
+        skill.app, name="skill",
+        help="Install the Tetra agent skill (teaches an AI to drive this CLI).",
+    )
+
+
+def main() -> None:
+    """Console-script entrypoint: configure logging, register commands, run."""
+    from tetra_cli.cli.output import configure_cli_logging
+    configure_cli_logging()
+    register_commands()
+    app()

tetra_cli/cli/commands/__init__.py

@@ -0,0 +1 @@
+"""Per-noun Typer subapps. Each module exposes `app: typer.Typer`."""

tetra_cli/cli/commands/auth.py

@@ -0,0 +1,201 @@
+"""tetra-cli auth {login,status,logout}
+
+Persists a `tetra_…` API key to `~/.tetra/cli_config.json` so subsequent
+CLI/MCP invocations resolve credentials automatically. The CLI and MCP
+server share `TetraConfig.from_env`, so saving once here makes any AI
+agent that runs `tetra-cli` or speaks the MCP protocol authenticated
+without per-call env-var juggling.
+
+Resolution priority (set by `TetraConfig.from_env`):
+    1. TETRA_API_KEY env var
+    2. ~/.tetra/cli_config.json (this file)
+    3. TETRA_USERNAME + credentials.json
+    4. TETRA_USERNAME + TETRA_PASSWORD (login)
+
+Env vars still override the saved config so users can flip backends
+(staging vs prod) without re-running `auth login`.
+"""
+import json
+import os
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+import httpx
+import typer
+
+from tetra_cli.cli.output import emit, emit_error
+
+DEFAULT_API_URL = "https://api.tetraoptum.com"
+
+
+app = typer.Typer(
+    no_args_is_help=True,
+    help="Save / inspect / clear the API key the CLI + MCP use to talk to Tetra.",
+)
+
+
+def _config_dir() -> Path:
+    return Path.home() / ".tetra"
+
+
+def _config_path() -> Path:
+    """Single source of truth for the saved-config location.
+
+    Reading via a function (not a module-level constant) lets tests
+    redirect `$HOME` to a tmp dir without monkeypatching this module.
+    """
+    return _config_dir() / "cli_config.json"
+
+
+def _verify_key(api_url: str, api_key: str) -> dict[str, Any]:
+    """Confirm the key works against `api_url` by hitting `/accounts/me`.
+
+    Returns the account payload on success; raises `ValueError` with a
+    short reason on failure. We never save an unverified key — that
+    would leave the user with a broken config that fails on every
+    subsequent invocation instead of upfront.
+    """
+    try:
+        resp = httpx.get(
+            f"{api_url}/api/v1/accounts/me",
+            headers={"Authorization": f"Bearer {api_key}"},
+            timeout=10.0,
+        )
+    except httpx.RequestError as exc:
+        raise ValueError(f"Could not reach {api_url}: {exc}") from exc
+    if resp.status_code == 401:
+        raise ValueError(
+            f"Backend rejected the key (HTTP 401). Either it's wrong, expired, "
+            f"or it was minted on a different backend. Mint a new one in Settings → "
+            f"API Keys on {api_url} and try again."
+        )
+    if resp.status_code != 200:
+        raise ValueError(f"HTTP {resp.status_code}: {resp.text[:200]}")
+    return resp.json()
+
+
+def _mask(token: str) -> str:
+    """Truncate a token for display. Keeps the prefix users see in
+    the API Keys list, drops the rest, e.g. `tetra_abcdef…`.
+    """
+    if not token:
+        return ""
+    if len(token) <= 12:
+        return token[:6] + "…"
+    return token[:12] + "…"
+
+
+@app.command("login")
+def login(
+    token: str | None = typer.Argument(
+        None,
+        metavar="API_KEY",
+        help="The `tetra_…` API key (alternative to --key).",
+    ),
+    key: str | None = typer.Option(
+        None, "--key", help="API key (`tetra_…`). Positional argument also accepted."
+    ),
+    url: str = typer.Option(
+        DEFAULT_API_URL,
+        "--url",
+        help=f"Backend base URL. Defaults to {DEFAULT_API_URL}.",
+    ),
+) -> None:
+    """Verify a `tetra_…` API key and save it to ~/.tetra/cli_config.json.
+
+    After this, every `tetra-cli` and `tetra-mcp` invocation
+    on this machine reads the saved key automatically — no env vars
+    needed. `TETRA_API_KEY` / `TETRA_API_URL` env vars still override
+    the saved values per-invocation if set.
+    """
+    raw = key or token
+    if not raw:
+        emit_error("missing_key", "Pass the API key as a positional arg or --key.")
+        return
+    raw = raw.strip()
+    if not raw.startswith("tetra_"):
+        emit_error(
+            "bad_key_format",
+            "API keys start with `tetra_`. Got: " + raw[:8] + "…",
+        )
+        return
+
+    try:
+        account = _verify_key(url, raw)
+    except ValueError as exc:
+        emit_error("verify_failed", str(exc))
+        return
+
+    cfg = {
+        "api_key": raw,
+        "api_url": url,
+        "saved_at": datetime.now(UTC).isoformat(),
+        "verified_username": account.get("username"),
+        "verified_uid": account.get("uid"),
+    }
+    _config_dir().mkdir(parents=True, exist_ok=True)
+    path = _config_path()
+    path.write_text(json.dumps(cfg, indent=2))
+    # API key on disk is sensitive — lock the file down to owner-only.
+    os.chmod(path, 0o600)
+
+    emit({
+        "saved": str(path),
+        "verified_username": account.get("username"),
+        "api_url": url,
+        "api_key": _mask(raw),
+    })
+
+
+@app.command("status")
+def status() -> None:
+    """Report which auth source the CLI will use on the next invocation.
+
+    Lets an AI/agent confirm "yes, I'm authenticated" before retrying a
+    failed call. Tokens are masked — full value never appears in output.
+    """
+    # Env vars win — report them first.
+    env_key = os.environ.get("TETRA_API_KEY")
+    if env_key:
+        emit({
+            "source": "env_api_key",
+            "api_key": _mask(env_key),
+            "api_url": os.environ.get("TETRA_API_URL", DEFAULT_API_URL),
+        })
+        return
+
+    env_username = os.environ.get("TETRA_USERNAME")
+    if env_username:
+        emit({
+            "source": "env_username",
+            "username": env_username,
+            "api_url": os.environ.get("TETRA_API_URL", DEFAULT_API_URL),
+        })
+        return
+
+    path = _config_path()
+    if path.exists():
+        data = json.loads(path.read_text())
+        emit({
+            "source": "saved_config",
+            "path": str(path),
+            "api_key": _mask(data.get("api_key", "")),
+            "api_url": data.get("api_url"),
+            "verified_username": data.get("verified_username"),
+            "saved_at": data.get("saved_at"),
+        })
+        return
+
+    emit({"source": "none", "hint": "Run `tetra-cli auth login <key>` to save."})
+
+
+@app.command("logout")
+def logout() -> None:
+    """Remove the saved config. Idempotent — does nothing if no file exists."""
+    path = _config_path()
+    if path.exists():
+        path.unlink()
+        emit({"removed": str(path)})
+    else:
+        emit({"removed": None, "hint": "Nothing to remove."})

tetra_cli/cli/commands/guide.py

@@ -0,0 +1,8 @@
+"""tetra-cli guide — print the canonical Tetra ontology guide for agents."""
+from tetra_cli.cli.output import emit
+from tetra_cli.ontology import ONTOLOGY_GUIDE
+
+
+def guide() -> None:
+    """Explain how to structure data: values (plan) vs goals (achieve) vs events (actuals)."""
+    emit({"guide": ONTOLOGY_GUIDE})

tetra_cli/cli/commands/messages.py

@@ -0,0 +1,161 @@
+"""tetra messages — real-time AI-thread stream (subscribe) and poll loop (watch).
+
+Only the streaming/polling commands live here: they have no single-return API
+mapping, so the @operation generator cannot express them. Every other
+AI-thread capability (read, post, reply, action) is a generated ``conversations``
+command:
+
+    tetra-cli conversations ai-read [--all]      # was: messages read
+    tetra-cli conversations ai-post "<text>"     # was: messages post
+    tetra-cli conversations ai-reply <uid> "<text>"   # was: messages reply
+    tetra-cli conversations ai-action --content ... --action '{...}'  # was: messages action
+
+Examples::
+
+    tetra messages subscribe              # SSE firehose, one JSON object per line
+    tetra messages watch --interval 5     # poll loop for external drivers
+"""
+import asyncio
+import json
+
+import typer
+
+import tetra_cli.cli.context as _ctx
+from tetra_cli.api_client import TetraClient
+from tetra_cli.api_client.operations import conversations as ops
+from tetra_cli.cli.output import emit_error, run_async
+
+app = typer.Typer(
+    no_args_is_help=True,
+    help="Stream (subscribe) or poll (watch) the AI thread in real time.",
+)
+
+
+def parse_sse_event(block: str) -> dict | None:
+    """Parse one SSE event block into {'id': str|None, 'data': dict}, or None
+    for comment/heartbeat/blank blocks. Field order within the block is
+    insignificant (the backend emits data then id)."""
+    event_id = None
+    data_lines = []
+    for line in block.splitlines():
+        if line.startswith(":"):  # comment / heartbeat
+            continue
+        if line.startswith("id:"):
+            event_id = line[3:].strip()
+        elif line.startswith("data:"):
+            data_lines.append(line[5:].strip())
+    if not data_lines:
+        return None
+    try:
+        return {"id": event_id, "data": json.loads("".join(data_lines))}
+    except json.JSONDecodeError:
+        return None
+
+
+def _subscribe_endpoint() -> tuple[str, str]:
+    """Return ``(origin, bearer_token)`` for the SSE stream.
+
+    Reuses the exact config the rest of the CLI uses (``TetraConfig.from_env()``
+    via :mod:`tetra_cli.api_client`). ``api_url`` is the bare origin (no
+    ``/api/v1``), so the caller appends the route path directly.
+    """
+    from tetra_cli.api_client import TetraConfig
+
+    cfg = TetraConfig.from_env()
+    return cfg.api_url.rstrip("/"), cfg.token
+
+
+@app.command("watch")
+def watch(
+    interval: float = typer.Option(5.0, "--interval", help="Seconds between polls."),
+    mark_read: bool = typer.Option(
+        True, "--mark-read/--no-mark-read",
+        help="Advance the cursor after printing.",
+    ),
+) -> None:
+    """Poll for unseen messages forever, printing each new batch as JSON lines."""
+
+    async def _poll_once(client: TetraClient, convo_uid: str) -> list:
+        result = await ops.get_unseen(client, convo_uid)
+        msgs = result.get("messages", [])
+        if msgs and mark_read:
+            await ops.mark_agent_read(client, convo_uid)
+        return msgs
+
+    async def _loop() -> None:
+        client = _ctx.build_client()
+        try:
+            convo = await ops.get_ai_conversation(client)
+            while True:
+                for m in await _poll_once(client, convo["uid"]):
+                    typer.echo(json.dumps(m))
+                await asyncio.sleep(interval)
+        finally:
+            await client.close()
+
+    try:
+        run_async(_loop())
+    except KeyboardInterrupt:  # pragma: no cover - interactive
+        raise typer.Exit(0)
+
+
+@app.command("subscribe")
+def subscribe(
+    reconnect: bool = typer.Option(
+        True, "--reconnect/--no-reconnect",
+        help="Auto-reconnect on disconnect.",
+    ),
+    reconnect_max_seconds: float = typer.Option(
+        30.0, "--reconnect-max-seconds",
+        help="Max backoff between reconnects.",
+    ),
+) -> None:
+    """Stream new AI-thread messages as JSON lines (real-time). Runs until killed.
+
+    Emits one JSON object per line per interaction; the firehose includes your
+    own messages — filter on api_key_uid downstream if needed.
+    """
+    import time
+
+    import httpx
+
+    base_url, token = _subscribe_endpoint()
+    url = f"{base_url}/api/v1/conversations/ai/stream"
+    last_id: str | None = None
+    backoff = 1.0
+
+    while True:
+        try:
+            req_headers = {
+                "Authorization": f"Bearer {token}",
+                "Accept": "text/event-stream",
+            }
+            if last_id:
+                req_headers["Last-Event-ID"] = last_id
+            with httpx.stream("GET", url, headers=req_headers, timeout=None) as resp:
+                if resp.status_code != 200:
+                    emit_error("stream_error", f"HTTP {resp.status_code}", exit_code=1)
+                    return
+                backoff = 1.0
+                block_lines: list[str] = []
+                for line in resp.iter_lines():
+                    if line == "":
+                        ev = parse_sse_event("\n".join(block_lines))
+                        block_lines = []
+                        if ev is None:
+                            continue
+                        if ev["id"]:
+                            last_id = ev["id"]
+                        typer.echo(json.dumps(ev["data"]))
+                    else:
+                        block_lines.append(line)
+        except KeyboardInterrupt:  # pragma: no cover - interactive
+            raise typer.Exit(0)
+        except (httpx.HTTPError, OSError) as exc:  # network error
+            if not reconnect:
+                emit_error("stream_error", str(exc), exit_code=1)
+                return
+        if not reconnect:
+            return
+        time.sleep(min(backoff, reconnect_max_seconds))
+        backoff = min(backoff * 2, reconnect_max_seconds)

tetra_cli/cli/commands/skill.py

@@ -0,0 +1,71 @@
+"""tetra-cli skill {install,show}
+
+Ships the agent-facing Tetra skill bundled inside this package out to where an
+AI coding agent discovers it (Claude Code: ``~/.claude/skills/``). Keeping the
+skill in the wheel means `pip install tetra-cli` delivers the client AND the
+instructions that teach an agent to drive it — one artifact, one version.
+"""
+from importlib import resources
+from pathlib import Path
+
+import typer
+
+from tetra_cli.cli.output import emit, emit_error
+
+app = typer.Typer(
+    no_args_is_help=True,
+    help="Install the Tetra agent skill (teaches an AI to drive this CLI).",
+)
+
+# Default skills root for Claude Code. Other agents (Codex, etc.) keep skills
+# elsewhere — point `--dir` at their skills directory for those.
+_DEFAULT_SKILLS_DIR = Path.home() / ".claude" / "skills"
+_SKILL_NAME = "tetra-cli"
+
+
+def _bundled_skill() -> str:
+    """Return the bundled SKILL.md text shipped inside the package."""
+    return resources.files("tetra_cli.skill").joinpath("SKILL.md").read_text(encoding="utf-8")
+
+
+@app.command("install")
+def install(
+    dir: Path = typer.Option(
+        _DEFAULT_SKILLS_DIR,
+        "--dir",
+        help="Skills directory to install into. Defaults to Claude Code's "
+        "~/.claude/skills; pass another agent's skills dir to target it.",
+    ),
+    force: bool = typer.Option(
+        False, "--force", help="Overwrite an existing tetra-cli skill."
+    ),
+) -> None:
+    """Copy the bundled Tetra skill into an agent's skills directory.
+
+    Writes ``<dir>/tetra-cli/SKILL.md``. Idempotent unless the file already
+    exists with different content — then it refuses without ``--force`` so a
+    user's local edits are never silently clobbered.
+    """
+    dest_dir = dir / _SKILL_NAME
+    dest = dest_dir / "SKILL.md"
+    content = _bundled_skill()
+
+    if dest.exists() and not force:
+        if dest.read_text(encoding="utf-8") == content:
+            emit({"installed": str(dest), "status": "already_current"})
+            return
+        emit_error(
+            "skill_exists",
+            f"{dest} already exists and differs. Re-run with --force to overwrite.",
+        )
+        return
+
+    dest_dir.mkdir(parents=True, exist_ok=True)
+    dest.write_text(content, encoding="utf-8")
+    emit({"installed": str(dest), "status": "ok"})
+
+
+@app.command("show")
+def show() -> None:
+    """Print the bundled skill to stdout (to inspect or pipe it somewhere)."""
+    typer.echo(_bundled_skill())

tetra_cli/cli/context.py

@@ -0,0 +1,13 @@
+"""Per-invocation context: builds an authenticated TetraClient from env."""
+from tetra_cli.api_client import TetraClient, TetraConfig
+
+
+def build_client() -> TetraClient:
+    """Build a TetraClient using TetraConfig.from_env().
+
+    Auth resolution priority (set one):
+        TETRA_API_KEY       - direct API key (tetra_...)
+        TETRA_USERNAME      - reads ~/.tetra/{username}_credentials.json
+        TETRA_USERNAME + TETRA_PASSWORD - logs in via API
+    """
+    return TetraClient(TetraConfig.from_env())