tetra-cli 0.2.0__py3-none-any.whl

tetra_cli/cli/generate.py

@@ -0,0 +1,282 @@
+"""Generate Typer commands from the operation registry.
+
+Typer reads a command function's parameters (name, annotation, default) to
+build its CLI. We synthesise a function with a real ``__signature__`` whose
+parameter defaults are ``typer.Option``/``typer.Argument`` objects, so Typer
+introspects it like a hand-written command. The body collects the parsed
+values, parses any JSON-blob options, and runs the op in-process via the
+existing emit/build_client glue.
+"""
+from __future__ import annotations
+
+import inspect
+import json as _json
+import sys
+from typing import Any, Optional
+
+import click
+import typer
+
+from tetra_cli import registry
+from tetra_cli.cli.output import emit, emit_error, run_async
+from tetra_cli.registry import OperationSpec, ParamSpec
+
+# `output="file"` ops (binary/CSV/zip/iCal downloads) ARE honored: the op
+# returns a ``(content_bytes, filename)`` tuple via ``TetraClient.download``
+# and the generated command writes the bytes to disk (or stdout) instead of
+# JSON-encoding them. See the file-output branch in ``build_typer_command``.
+#
+# superuser ops are skipped entirely (admin-only; not part of the shareable
+# user-scoped surface). TODO: the text:<formatter> / stream `output` formatters
+# are not yet honored — those ops are still emitted as JSON. Deferred.
+
+
+def _clear_flag(name: str) -> str:
+    """Companion boolean flag that clears a repeatable list param to []."""
+    return f"--clear-{name.replace('_', '-')}"
+
+
+def _write_file_result(result: Any, output: str | None) -> None:
+    """Write an ``output="file"`` op's ``(bytes, filename)`` result to disk.
+
+    Destination resolution:
+      * ``output == "-"`` -> raw bytes to ``sys.stdout.buffer`` (no JSON).
+      * ``output`` set    -> that path.
+      * otherwise         -> the server-supplied ``filename`` in the cwd.
+
+    On success (non-stdout) emits ``{"saved": <path>, "bytes": <n>}`` as JSON
+    so the CLI's single-line machine-readable contract still holds. The raw
+    bytes are never JSON-serialized.
+
+    Args:
+        result: The ``(content_bytes, filename)`` tuple the op returned.
+        output: The ``--output`` value (path, ``"-"``, or None).
+    """
+    content, filename = result
+    if output == "-":
+        sys.stdout.buffer.write(content)
+        sys.stdout.buffer.flush()
+        return
+    path = output or filename
+    with open(path, "wb") as fh:
+        fh.write(content)
+    emit({"saved": path, "bytes": len(content)})
+
+
+def _typer_default(name: str, ps: ParamSpec, sig: inspect.Signature) -> Any:
+    """Build the typer.Argument/Option default that drives Typer's parser.
+
+    For an OPTION, the Typer default mirrors the op signature's own default so
+    that omitting the flag yields the op's intended value (e.g. ``limit=50``)
+    rather than a spurious ``None`` that would override it. Repeatable/list and
+    boolean options keep ``None``/``False`` as before (the impl normalizes an
+    empty list back to None when appropriate). Required params (no signature
+    default) stay positional arguments.
+    """
+    if ps.kind == "argument":
+        return typer.Argument(..., help=ps.help)
+    flags = ps.flags or (f"--{name.replace('_', '-')}",)
+    kwargs: dict[str, Any] = {"help": ps.help}
+    if ps.min is not None:
+        kwargs["min"] = ps.min
+    if ps.max is not None:
+        kwargs["max"] = ps.max
+    if ps.choices:
+        # Constrain the option to a fixed set; Click validates and lists the
+        # choices in --help. The op still receives the raw string value.
+        kwargs["click_type"] = click.Choice(ps.choices)
+    # Repeatable options collect N values; Typer/Click needs None (not the op's
+    # default) so the impl can tell "flag omitted" from "flag given empty".
+    if ps.repeatable:
+        return typer.Option(None, *flags, **kwargs)
+    sig_default = sig.parameters[name].default
+    cli_default = None if sig_default is inspect.Parameter.empty else sig_default
+    return typer.Option(cli_default, *flags, **kwargs)
+
+
+def _annotation(name: str, ps: ParamSpec, sig: inspect.Signature) -> Any:
+    """Pick the CLI-facing annotation Typer should parse the value as.
+
+    Repeatable -> Optional[list[str]] (collects N values), JSON-blob -> str
+    (we parse it ourselves), otherwise infer int/float/bool/str from the op's
+    own annotation when present.
+    """
+    if ps.repeatable:
+        return Optional[list[str]]
+    if ps.json:
+        return Optional[str]
+    # min/max bounds only make sense for numbers -> treat as int.
+    if ps.min is not None or ps.max is not None:
+        return Optional[int]
+    param = sig.parameters[name]
+    ann = param.annotation
+    raw = repr(ann)
+    if "int" in raw:
+        return Optional[int]
+    if "float" in raw:
+        return Optional[float]
+    if "bool" in raw:
+        return Optional[bool]
+    # No usable annotation: infer the CLI type from a non-None signature
+    # default so an int default (e.g. limit=50) is parsed as an int, not a
+    # string. (bool checked before int: bool is a subclass of int.)
+    if ann is inspect.Parameter.empty and param.default not in (
+        inspect.Parameter.empty, None,
+    ):
+        dft = param.default
+        if isinstance(dft, bool):
+            return Optional[bool]
+        if isinstance(dft, int):
+            return Optional[int]
+        if isinstance(dft, float):
+            return Optional[float]
+    if ps.kind == "argument":
+        return str
+    return Optional[str]
+
+
+def build_typer_command(spec: OperationSpec):
+    """Return (command_name, callable) for ``group.command(name)(callable)``."""
+    sig = spec.signature()
+    op_params = spec.op_param_names()
+    is_file = spec.output == "file"
+    # For file ops, synthesize an `--output` (or `--out` if the op already owns
+    # a param literally named `output`) flag that picks the write destination.
+    output_kwarg = "out" if "output" in op_params else "output"
+    output_flags = (
+        ("--out",) if output_kwarg == "out" else ("--output", "-o")
+    )
+
+    parameters: list[inspect.Parameter] = []
+    # Track which op params get a `--clear-<name>` companion and the synthetic
+    # kwarg name that carries that boolean into impl.
+    clear_kwargs: dict[str, str] = {}
+    for name in op_params:
+        ps = spec.params.get(name, ParamSpec())
+        default = _typer_default(name, ps, sig)
+        ann = _annotation(name, ps, sig)
+        parameters.append(inspect.Parameter(
+            name,
+            inspect.Parameter.POSITIONAL_OR_KEYWORD,
+            default=default,
+            annotation=ann,
+        ))
+        if ps.kind == "option" and ps.repeatable and ps.clears:
+            clear_name = f"clear_{name}"
+            clear_kwargs[name] = clear_name
+            parameters.append(inspect.Parameter(
+                clear_name,
+                inspect.Parameter.POSITIONAL_OR_KEYWORD,
+                default=typer.Option(
+                    False, _clear_flag(name),
+                    help=f"Clear {name} (send an empty list).",
+                ),
+                annotation=bool,
+            ))
+
+    if is_file:
+        parameters.append(inspect.Parameter(
+            output_kwarg,
+            inspect.Parameter.POSITIONAL_OR_KEYWORD,
+            default=typer.Option(
+                None, *output_flags,
+                help="Write to this path (default: server filename in cwd; "
+                     "'-' for stdout).",
+            ),
+            annotation=Optional[str],
+        ))
+
+    def impl(**kwargs: Any) -> None:
+        from tetra_cli.cli import context as _ctx
+        call_kwargs: dict[str, Any] = {}
+        for name in op_params:
+            ps = spec.params.get(name, ParamSpec())
+            val = kwargs.get(name)
+            if ps.json and val is not None:
+                try:
+                    val = _json.loads(val)
+                except _json.JSONDecodeError as exc:
+                    emit_error("invalid_json", f"--{name} is not valid JSON: {exc}")
+                    return
+            if ps.repeatable and ps.clears and kwargs.get(clear_kwargs[name]):
+                # Explicit --clear-<name> wins: send [] to clear the list.
+                val = []
+            elif ps.repeatable and val == [] and not ps.clears:
+                val = None
+            call_kwargs[name] = val
+
+        async def _call() -> Any:
+            client = _ctx.build_client()
+            try:
+                return await spec.func(client, **call_kwargs)
+            finally:
+                await client.close()
+
+        try:
+            result = run_async(_call())
+            if is_file:
+                _write_file_result(result, kwargs.get(output_kwarg))
+            else:
+                emit(result)
+        except (typer.Exit, SystemExit):
+            # Control-flow signals (e.g. emit_error's SystemExit, an op's
+            # typer.Exit) must propagate with their own exit code, not be
+            # rewrapped as an api_error.
+            raise
+        except Exception as exc:  # noqa: BLE001
+            emit_error("api_error", str(exc))
+
+    impl.__signature__ = inspect.Signature(parameters)  # type: ignore[attr-defined]
+    impl.__name__ = spec.command.replace("-", "_").replace(" ", "_")
+    impl.__doc__ = spec.summary
+    return spec.command, impl
+
+
+def register_generated(app: typer.Typer) -> set[str]:
+    """Build a Typer command for every non-manual registered op and mount it.
+
+    A spec's ``cli`` string may have any number of segments: the last segment
+    is the command name, every earlier segment is a (possibly nested) Typer
+    group. Intermediate groups are created on demand and cached by their full
+    path prefix so sibling commands share the same parent group
+    (``goals metrics record`` and ``goals metrics edit`` reuse one ``metrics``).
+
+    Returns:
+        The set of top-level group names produced. The app registers generated
+        groups first and skips any manual command module whose group the
+        registry now owns, so annotating an op never collides with a leftover
+        hand-written command for the same group.
+    """
+    registry.load_operations()
+    # Cache nested Typer groups by their full path prefix, e.g. "goals" and
+    # "goals metrics". The empty prefix maps to the root app.
+    groups: dict[str, typer.Typer] = {"": app}
+    top_groups: set[str] = set()
+    for spec in registry.all():
+        # superuser ops are admin-only (server 403s for normal keys) — keep them
+        # off the shareable agent surface entirely.
+        if spec.manual or spec.superuser:
+            continue
+        segments = spec.cli.split()
+        if len(segments) > 1:
+            top_groups.add(segments[0])
+        *group_path, command_name = segments
+        # Walk/create the chain of intermediate groups.
+        prefix = ""
+        for seg in group_path:
+            child_prefix = f"{prefix} {seg}".strip()
+            child = groups.get(child_prefix)
+            if child is None:
+                child = typer.Typer(no_args_is_help=True)
+                groups[child_prefix] = child
+                # Give each generated group a non-blank description so the
+                # parent's --help isn't a wall of empty rows. Derived from the
+                # segment name (e.g. "goals" -> "Goals commands").
+                groups[prefix].add_typer(
+                    child, name=seg, help=f"{seg.replace('-', ' ').capitalize()} commands",
+                )
+            prefix = child_prefix
+        parent = groups[prefix]
+        _, fn = build_typer_command(spec)
+        parent.command(command_name, help=spec.summary)(fn)
+    return top_groups

tetra_cli/cli/output.py

@@ -0,0 +1,58 @@
+"""JSON output, error reporting, and async glue for the CLI."""
+import asyncio
+import json
+import sys
+from collections.abc import Coroutine
+from datetime import date, datetime
+from typing import Any, TypeVar
+
+T = TypeVar("T")
+
+# Module-level pretty flag. The root Typer callback toggles this.
+_pretty = False
+
+
+def set_pretty(value: bool) -> None:
+    """Toggle indented JSON output. Called by the root --pretty option."""
+    global _pretty
+    _pretty = value
+
+
+def _serialize(obj: Any) -> Any:
+    if isinstance(obj, (datetime, date)):
+        return obj.isoformat()
+    if hasattr(obj, "__dict__"):
+        return {k: v for k, v in obj.__dict__.items() if not k.startswith("_")}
+    return str(obj)
+
+
+def emit(data: Any) -> None:
+    """Print JSON to stdout. Single exit point for all CLI output."""
+    if _pretty:
+        print(json.dumps(data, default=_serialize, indent=2))
+    else:
+        print(json.dumps(data, default=_serialize))
+
+
+def emit_error(error: str, message: str, exit_code: int = 1) -> None:
+    """Print JSON error to stderr and exit."""
+    print(json.dumps({"error": error, "message": message}), file=sys.stderr)
+    sys.exit(exit_code)
+
+
+def run_async(coro: Coroutine[Any, Any, T]) -> T:
+    """Run an async coroutine from a sync Typer command body."""
+    return asyncio.run(coro)
+
+
+def configure_cli_logging() -> None:
+    """Route all logging to stderr so stdout stays clean for JSON output."""
+    import logging
+    root = logging.getLogger()
+    for handler in root.handlers[:]:
+        root.removeHandler(handler)
+    stderr_handler = logging.StreamHandler(sys.stderr)
+    stderr_handler.setFormatter(
+        logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+    )
+    root.addHandler(stderr_handler)

tetra_cli/mcp_gen.py

@@ -0,0 +1,137 @@
+"""Generate MCP tools from the operation registry.
+
+FastMCP introspects a tool function's typed parameters to build its input
+schema. We synthesise an async function with an injected ``__signature__``
+(json params -> dict, repeatable -> list[str], else str/int/float/bool, with
+op defaults preserved) and register it on the FastMCP instance passed in by the
+caller. This module must NOT import ``mcp`` — the FastMCP object is injected, so
+the slim package's deps stay httpx+typer and the no-backend-leak invariant holds.
+
+Optionality is signalled purely by the synthesised parameter's DEFAULT value:
+a parameter with ``default=None`` is optional to FastMCP regardless of its
+annotation, so we keep annotations bare (``dict``, ``list[str]``, ``str`` …)
+rather than wrapping them in ``Optional[...]``. Required op params (no signature
+default) get no default in the synthesised signature.
+
+TODO: ``output="text:<formatter>"`` formatting (tools currently return the raw
+JSON-able op result) and ``choices`` -> ``typing.Literal`` constraints are
+deferred to a later phase; don't mistake these for working.
+"""
+from __future__ import annotations
+
+import base64
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+from tetra_cli import registry
+from tetra_cli.registry import OperationSpec, ParamSpec
+
+
+def _file_result_to_tool_payload(result: Any) -> Any:
+    """Turn a file op's ``(bytes, filename)`` return into a tool-friendly dict.
+
+    ``output="file"`` ops (data export, iCal, projection CSV/zip) download raw
+    bytes for the CLI to write to disk. An MCP tool has no disk sink, so return
+    the content inline instead: UTF-8 text when the body decodes (JSON exports,
+    iCal, CSV), base64 otherwise (zip archives). This lets an agent reach the
+    same export capabilities a human has, without leaving the conversation.
+    """
+    if not (isinstance(result, tuple) and len(result) == 2):
+        return result  # Not a (bytes, filename) tuple — pass through unchanged.
+    content, filename = result
+    if isinstance(content, (bytes, bytearray)):
+        try:
+            return {"filename": filename, "content": bytes(content).decode("utf-8")}
+        except UnicodeDecodeError:
+            return {
+                "filename": filename,
+                "encoding": "base64",
+                "content_base64": base64.b64encode(bytes(content)).decode("ascii"),
+            }
+    return {"filename": filename, "content": content}
+
+
+def _annotation(name: str, ps: ParamSpec, sig: inspect.Signature) -> Any:
+    """Pick the MCP-facing annotation FastMCP should expose for a param.
+
+    JSON-blob params take a ``dict`` (MCP passes structured objects directly),
+    repeatable params take ``list[str]``, otherwise infer bool/int/float/str
+    from the op's own annotation. Optionality is carried by the default value,
+    not by wrapping in ``Optional`` — see the module docstring.
+    """
+    if ps.json:
+        return dict
+    if ps.repeatable:
+        return list[str]
+    ann = sig.parameters[name].annotation
+    raw = repr(ann)
+    # bool checked before int: bool is a subclass of int.
+    if "bool" in raw:
+        return bool
+    if "int" in raw:
+        return int
+    if "float" in raw:
+        return float
+    return str
+
+
+def _build_tool(spec: OperationSpec, client_factory: Callable[[], Any]):
+    """Synthesise the async tool function FastMCP will introspect and call."""
+    sig = spec.signature()
+    op_params = spec.op_param_names()
+    required = set(spec.required_param_names())
+
+    parameters: list[inspect.Parameter] = []
+    for name in op_params:
+        ps = spec.params.get(name, ParamSpec())
+        ann = _annotation(name, ps, sig)
+        if name in required:
+            # No default -> FastMCP treats it as required in the input schema.
+            parameters.append(inspect.Parameter(
+                name, inspect.Parameter.KEYWORD_ONLY, annotation=ann))
+        else:
+            sig_default = sig.parameters[name].default
+            default = None if sig_default is inspect.Parameter.empty else sig_default
+            # default present -> optional, even with a bare (non-Optional) annotation.
+            parameters.append(inspect.Parameter(
+                name, inspect.Parameter.KEYWORD_ONLY, default=default,
+                annotation=ann))
+
+    is_file = spec.output == "file"
+
+    async def impl(**kwargs: Any) -> Any:
+        client = client_factory()
+        result = await spec.func(client, **kwargs)
+        return _file_result_to_tool_payload(result) if is_file else result
+
+    impl.__signature__ = inspect.Signature(parameters)  # type: ignore[attr-defined]
+    impl.__name__ = spec.mcp_tool or spec.func.__name__
+    impl.__doc__ = spec.summary
+    return impl
+
+
+def register_mcp_tools(mcp: Any, client_factory: Callable[[], Any]) -> int:
+    """Register an MCP tool for every non-manual registered op.
+
+    Args:
+        mcp: a FastMCP-like object exposing ``.tool(name=, description=)`` -> decorator.
+        client_factory: returns a shared TetraClient for tool calls (not closed per call).
+
+    Returns:
+        The number of tools registered.
+    """
+    registry.load_operations()
+    count = 0
+    for spec in registry.all():
+        # manual = hand-written elsewhere; superuser = admin-only (server 403s
+        # normal keys); stream = long-lived SSE that can't be a single tool
+        # return. File ops ARE exposed — their content is returned inline (see
+        # _file_result_to_tool_payload) so an agent has the same exports a human
+        # does.
+        if spec.manual or spec.superuser or spec.output == "stream":
+            continue
+        fn = _build_tool(spec, client_factory)
+        mcp.tool(name=spec.mcp_tool, description=spec.summary)(fn)
+        count += 1
+    return count

tetra_cli/ontology.py

@@ -0,0 +1,70 @@
+"""Canonical agent-facing ontology for Tetra: values, goals, events.
+
+This is the slim-package copy of :data:`ONTOLOGY_GUIDE`. The CLI (``tetra-cli
+guide``) returns it verbatim. It carries no backend dependencies so the CLI
+package stays free of any ``tetra.*`` imports. The backend keeps its own copy
+at ``tetra.core.ontology`` (which also owns the goal-linkage nudge logic).
+"""
+from __future__ import annotations
+
+ONTOLOGY_GUIDE = """\
+# Tetra: Values, Goals, Events
+
+Tetra aligns your **time and money** with what matters. Three layers:
+
+**Values — how you *plan* to spend time or money.** General, durable life areas,
+arranged hierarchically. A value can carry a *schedule*: temporal
+(`see friends Thu 6-9pm`) or financial (`$215/mo bill`). Every value descends
+from one of the six **core values** — the top-level life domains: Intellect,
+Willpower, Vitality, Spirit, Charisma, Creativity. (This is enforced: a value's
+root must be a core value, so always create under one.) Values answer *"where
+should my time and money go?"*
+
+**Goals — concrete things you *achieve*, with metrics.** Goals hang off values
+as **skill trees**: the specific, trackable things you'll do to get excellent at
+a value. A goal has expected time/cost, dependencies, and a metric (reps, pages,
+$, complete). Goals answer *"what concretely will I do for this value?"*
+
+**Events — what *actually* happened.** Every event records real time/money and
+links to a goal and/or value. Events answer *"what did I really do?"* and are
+how progress and planned-vs-actual comparison work.
+
+## Granularity — be as granular as the data you'll match against.
+
+- Granular is *good* when it maps to real actuals or feeds a projection. Per-bill
+  values (`Financial > Bills > Internet`) let imported bank/credit-card data
+  reconcile planned vs. actual spend. Granular time-off
+  (`Sandia > Time Off > Vacation/Flex/...`) feeds projections like *"when will I
+  have enough PTO + savings for a vacation?"*
+- The real anti-patterns are **unattributed events** (time/money logged against
+  no value) and **goals not linked to any value** (orphaned skill-tree
+  branches) — not depth itself.
+
+## When acting for a user
+
+Put plans in values, achievements in goals, actuals in events; attach every
+event to a value/goal; keep new values under an existing core value; prefer
+reusing an existing value/goal over creating a near-duplicate.
+
+## Report what you do (required)
+
+After any write — creating, editing, moving, or deleting a value, goal, or
+event — post a short **action report** to the user's Tetra AI thread so the
+user and every other AI share the same history. Use the messages API
+(``POST /conversations/{ai_uid}/messages`` with ``interaction_type='action'``)
+or the ``log_action`` tool. Each action report must carry: ``action_type``
+(e.g. value_moved, goal_created, event_logged), ``subject_type``
+(value | goal | event), ``subject_uid``, and ``subject_name`` set to the
+entity's FULL canonical name (not a leaf) — the app uses ``subject_name`` to
+render the card and deep-link it to the entity's detail view — plus a one-line
+summary, the before/after, and a **reason** for the change. When you act because the user
+replied to an earlier action, set ``reply_to_uid`` to that action so the
+thread stays threaded. Before acting, poll ``GET .../agent/unseen`` (or the
+``get_unseen_messages`` tool) to pick up the user's replies and honor them.
+Instead of polling, you may register a push webhook (``register_webhook`` tool
+or ``tetra messages webhook set``) and Tetra will POST new user messages to
+your endpoint as they arrive. To react in real time without a webhook, run
+``tetra messages subscribe`` — an SSE stream that pushes each new AI-thread
+message as a JSON line (replays anything missed, then live); it's a firehose,
+so ignore your own ``api_key_uid`` echoes.
+"""

tetra_cli/registry.py

@@ -0,0 +1,118 @@
+"""Single source of truth for the agent surface.
+
+`@operation` annotates an async op function with the metadata both the CLI
+generator and the MCP generator need: command path, params, output kind, and
+the API route(s) it covers (for the parity guard). The op function body stays
+the executor — this only records surface metadata.
+"""
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ParamSpec:
+    """How one op parameter is exposed on the CLI/MCP surface."""
+    kind: str = "option"                 # "argument" | "option"
+    flags: tuple[str, ...] = ()          # e.g. ("--tag",); empty -> derived
+    help: str | None = None
+    repeatable: bool = False             # list-valued (repeatable CLI option / MCP array)
+    json: bool = False                   # CLI parses a JSON string; MCP passes a dict
+    clears: bool = False                 # allow empty -> send [] (clear a list)
+    choices: list[str] | None = None
+    min: int | None = None
+    max: int | None = None
+
+
+def arg(*, help: str | None = None) -> ParamSpec:
+    """A positional CLI argument (required)."""
+    return ParamSpec(kind="argument", help=help)
+
+
+def opt(*flags: str, help: str | None = None, repeatable: bool = False,
+        json: bool = False, clears: bool = False,
+        choices: list[str] | None = None,
+        min: int | None = None, max: int | None = None) -> ParamSpec:
+    """A CLI option (--flag)."""
+    return ParamSpec(kind="option", flags=tuple(flags), help=help,
+                     repeatable=repeatable, json=json, clears=clears,
+                     choices=choices, min=min, max=max)
+
+
+@dataclass
+class OperationSpec:
+    func: Callable[..., Any]
+    cli: str
+    summary: str
+    covers: list[tuple[str, str]]
+    params: dict[str, ParamSpec] = field(default_factory=dict)
+    mcp_tool: str | None = None
+    superuser: bool = False
+    output: str = "json"                 # "json" | "text:<formatter>" | "stream" | "file"
+    manual: bool = False
+
+    @property
+    def group(self) -> str:
+        return self.cli.split(" ", 1)[0]
+
+    @property
+    def command(self) -> str:
+        parts = self.cli.split(" ", 1)
+        return parts[1] if len(parts) > 1 else parts[0]
+
+    def signature(self) -> inspect.Signature:
+        return inspect.signature(self.func)
+
+    def op_param_names(self) -> list[str]:
+        """Op params excluding the leading `client`."""
+        return [p for p in self.signature().parameters if p != "client"]
+
+    def required_param_names(self) -> list[str]:
+        """Op params (excluding client) with no default = required."""
+        out = []
+        for name, p in self.signature().parameters.items():
+            if name == "client":
+                continue
+            if p.default is inspect.Parameter.empty:
+                out.append(name)
+        return out
+
+
+REGISTRY: list[OperationSpec] = []
+
+
+def operation(*, cli: str, summary: str, covers: list[tuple[str, str]],
+              params: dict[str, ParamSpec] | None = None,
+              mcp_tool: str | None = None, superuser: bool = False,
+              output: str = "json", manual: bool = False):
+    """Register `func` in REGISTRY with its surface metadata. Returns func unchanged."""
+    def deco(func: Callable[..., Any]) -> Callable[..., Any]:
+        spec = OperationSpec(
+            func=func, cli=cli, summary=summary, covers=list(covers),
+            params=dict(params or {}),
+            mcp_tool=mcp_tool or func.__name__,
+            superuser=superuser, output=output, manual=manual,
+        )
+        func.__operation__ = spec  # type: ignore[attr-defined]
+        REGISTRY.append(spec)
+        return func
+    return deco
+
+
+def all() -> list[OperationSpec]:
+    """All registered operation specs (call load_operations() first to populate)."""
+    return list(REGISTRY)
+
+
+def load_operations() -> None:
+    """Import every operations submodule so their @operation decorators run."""
+    import importlib
+    import pkgutil
+
+    from tetra_cli.api_client import operations as ops_pkg
+
+    for info in pkgutil.iter_modules(ops_pkg.__path__):
+        importlib.import_module(f"tetra_cli.api_client.operations.{info.name}")