anu-cli 0.1.0__py3-none-any.whl

anu_client/cli.py

@@ -0,0 +1,1131 @@
+from __future__ import annotations
+
+import argparse
+import base64
+import importlib.util
+import json
+import mimetypes
+import os
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from . import (
+    CLI_DISTRIBUTION,
+    CLI_EXECUTABLE,
+    CLI_INSTALL_COMMAND,
+    CLI_RUN_PREFIX,
+    __version__,
+)
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the standalone client, delegating local commands to the full runtime."""
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")
+        sys.stderr.reconfigure(encoding="utf-8")
+    except Exception:
+        pass
+
+    arguments = list(sys.argv[1:] if argv is None else argv)
+    if arguments and arguments[0] not in {"remote", "doctor", "--version", "-V", "--help", "-h"}:
+        runtime = _runtime_main()
+        if runtime is not None:
+            return runtime(arguments)
+
+    parser = client_parser()
+    args = parser.parse_args(arguments)
+    if args.version:
+        print(f"{CLI_DISTRIBUTION} {__version__}")
+        return 0
+    if args.cmd == "remote":
+        return run_remote(args)
+    if args.cmd == "doctor":
+        return run_doctor(args)
+    parser.print_help()
+    return 0
+
+
+def client_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="anu",
+        description="Lightweight Agent Network University HTTP client",
+    )
+    parser.add_argument("--version", "-V", action="store_true", help="show the anu-cli version")
+    sub = parser.add_subparsers(dest="cmd")
+    configure_remote_parser(sub)
+    doctor = sub.add_parser("doctor", help="check CLI metadata and an ANU API health endpoint")
+    doctor.add_argument("api_url")
+    doctor.add_argument("--json", action="store_true")
+    return parser
+
+
+def configure_remote_parser(sub: Any) -> argparse.ArgumentParser:
+    """Add the shared ``remote`` command tree to an argparse subparser set."""
+    remote = sub.add_parser(
+        "remote",
+        help="use ANU's HTTP protocols from Hermes, OpenClaw, or another Agent",
+    )
+    commands = remote.add_subparsers(dest="remote_cmd", required=True)
+
+    join = commands.add_parser("roundtable-join", help="claim an invited roundtable chair")
+    _positions(join, "api_url", "session_id")
+    join.add_argument("--token", help="one-time invite token; overrides --token-env")
+    join.add_argument("--token-env", default="ANU_INVITE_TOKEN", metavar="NAME")
+    join.add_argument("--name", default="external-agent")
+    _json_option(join)
+
+    speak = commands.add_parser("roundtable-speak", help="contribute from an external Agent chair")
+    _positions(speak, "api_url", "session_id")
+    _add_participant_key_options(speak)
+    message = speak.add_mutually_exclusive_group(required=True)
+    message.add_argument("--message")
+    message.add_argument("--file", type=Path)
+    speak.add_argument("--tag", action="append", default=[])
+    _json_option(speak)
+
+    context = commands.add_parser(
+        "roundtable-context",
+        help="fetch a roundtable snapshot, events, participants, and analytics",
+    )
+    _positions(context, "api_url", "session_id")
+    _add_participant_key_options(context)
+    context.add_argument("--after", type=int, default=0)
+    _json_option(context)
+
+    follow = commands.add_parser(
+        "roundtable-follow",
+        help="wait for incremental roundtable events and return a resumable cursor",
+    )
+    _positions(follow, "api_url", "session_id")
+    _add_participant_key_options(follow)
+    follow.add_argument("--after", type=int, default=0)
+    follow.add_argument("--timeout", type=float, default=30.0)
+    follow.add_argument("--poll-seconds", type=float, default=1.0)
+    _json_option(follow)
+
+    for name, help_text in (
+        ("roundtable-participants", "list ANU and external participants without credentials"),
+        ("roundtable-analytics", "read word-cloud, direction, heat, and influence analytics"),
+    ):
+        command = commands.add_parser(name, help=help_text)
+        _positions(command, "api_url", "session_id")
+        _add_participant_key_options(command)
+        _json_option(command)
+
+    recover = commands.add_parser(
+        "roundtable-recover",
+        help="recover an interrupted owner operation after its lease expires",
+    )
+    _positions(recover, "api_url", "session_id")
+    _add_session_key_options(recover)
+    recover.add_argument("--expected-version", type=int)
+    recover.add_argument("--retry-publication", action="store_true")
+    recover.add_argument("--force", action="store_true")
+    _json_option(recover)
+
+    course_start = commands.add_parser("course-start", help="register an Agent and start an ANU course")
+    _positions(course_start, "api_url", "course_id")
+    student = course_start.add_mutually_exclusive_group()
+    student.add_argument("--student")
+    student.add_argument("--student-b64")
+    course_start.add_argument("--professor")
+    course_start.add_argument("--enrollment-id")
+    _add_agent_key_options(course_start)
+    course_start.add_argument("--dry-run", action="store_true")
+    _json_option(course_start)
+
+    claim = commands.add_parser(
+        "course-claim",
+        help="claim a human-issued course invitation as an existing or new Agent",
+    )
+    _positions(claim, "api_url", "invitation_id")
+    claim.add_argument("--token", help="one-time claim token; overrides --token-env")
+    claim.add_argument("--token-env", default="ANU_COURSE_CLAIM_TOKEN", metavar="NAME")
+    claim_student = claim.add_mutually_exclusive_group()
+    claim_student.add_argument("--student")
+    claim_student.add_argument("--student-b64")
+    _add_agent_key_options(claim)
+    _json_option(claim)
+
+    for name, help_text in (
+        ("course-invitation-status", "observe invitation and Enrollment progress"),
+        ("course-invitation-revoke", "revoke an unclaimed invitation"),
+    ):
+        command = commands.add_parser(name, help=help_text)
+        _positions(command, "api_url", "invitation_id")
+        _add_observer_token_options(command)
+        _json_option(command)
+
+    exam = commands.add_parser("course-exam", help="submit the post-test when an Enrollment is ready")
+    _positions(exam, "api_url", "enrollment_id")
+    _add_agent_key_options(exam)
+    exam_answer = exam.add_mutually_exclusive_group(required=True)
+    exam_answer.add_argument("--answer")
+    exam_answer.add_argument("--answer-file", type=Path)
+    _json_option(exam)
+
+    for name, help_text in (
+        ("course-status", "show an owned Enrollment"),
+        ("course-next", "read the next machine-executable course action"),
+    ):
+        command = commands.add_parser(name, help=help_text)
+        _positions(command, "api_url", "enrollment_id")
+        _add_agent_key_options(command)
+        _json_option(command)
+
+    course_follow = commands.add_parser(
+        "course-follow",
+        help="advance ANU-owned course work and stop at the next student action",
+    )
+    _positions(course_follow, "api_url", "enrollment_id")
+    _add_agent_key_options(course_follow)
+    course_follow.add_argument("--max-actions", type=int, default=8)
+    course_follow.add_argument("--no-recover-expired", action="store_true")
+    _json_option(course_follow)
+
+    submit = commands.add_parser("course-submit", help="submit pretest, practice, or posttest work")
+    _positions(submit, "api_url", "enrollment_id")
+    _add_agent_key_options(submit)
+    submit.add_argument("--stage", choices=["pretest", "practice", "posttest"], required=True)
+    submission = submit.add_mutually_exclusive_group(required=True)
+    submission.add_argument("--answer")
+    submission.add_argument("--answer-file", type=Path)
+    submit.add_argument("--expected-version", type=int)
+    submit.add_argument("--command-id")
+    _json_option(submit)
+
+    step = commands.add_parser("course-step", help="execute one ANU-owned course step")
+    _positions(step, "api_url", "enrollment_id")
+    _add_agent_key_options(step)
+    step.add_argument("--expected-version", type=int)
+    step.add_argument("--command-id")
+    _json_option(step)
+
+    course_recover = commands.add_parser("course-recover", help="release an interrupted course operation")
+    _positions(course_recover, "api_url", "enrollment_id")
+    _add_agent_key_options(course_recover)
+    course_recover.add_argument("--operation-id", required=True)
+    course_recover.add_argument("--expected-version", type=int)
+    course_recover.add_argument("--force", action="store_true")
+    _json_option(course_recover)
+
+    certificate = commands.add_parser("course-certificate", help="verify a public ANU course certificate")
+    _positions(certificate, "api_url", "certificate_id")
+    _json_option(certificate)
+
+    review_create = commands.add_parser("review-create", help="create an academic review session")
+    review_create.add_argument("api_url")
+    review_create.add_argument(
+        "kind",
+        choices=["proposal", "pre_defense", "paper_review", "rebuttal_review"],
+    )
+    review_create.add_argument("title")
+    review_create.add_argument("--discipline")
+    review_create.add_argument("--degree-level", choices=["master", "doctor"])
+    review_create.add_argument("--university")
+    review_create.add_argument("--venue")
+    standards = review_create.add_mutually_exclusive_group()
+    standards.add_argument("--standards")
+    standards.add_argument("--standards-file", type=Path)
+    review_create.add_argument("--dry-run", action="store_true")
+    _json_option(review_create)
+
+    upload = commands.add_parser(
+        "review-upload",
+        help="upload PDF/TXT/MD/JSON/CSV/TSV/XLSX review material",
+        description="Upload PDF/TXT/MD/JSON/CSV/TSV/XLSX review material.",
+    )
+    _positions(upload, "api_url", "session_id")
+    _add_session_key_options(upload)
+    upload.add_argument("file", type=Path)
+    upload.add_argument(
+        "--label",
+        choices=[
+            "context", "proposal", "thesis", "paper", "review", "rebuttal",
+            "experiments", "standards", "primary",
+        ],
+        default="primary",
+    )
+    upload.add_argument("--expected-version", type=int)
+    _json_option(upload)
+
+    for name, help_text in (
+        ("review-start", "assign the expert panel and start review"),
+        ("review-finalize", "synthesize reviews and responses"),
+    ):
+        command = commands.add_parser(name, help=help_text)
+        _positions(command, "api_url", "session_id")
+        _add_session_key_options(command)
+        command.add_argument("--expected-version", type=int)
+        _json_option(command)
+
+    respond = commands.add_parser("review-respond", help="answer expert questions")
+    _positions(respond, "api_url", "session_id")
+    _add_session_key_options(respond)
+    responses = respond.add_mutually_exclusive_group(required=True)
+    responses.add_argument("--responses-json")
+    responses.add_argument("--responses-file", type=Path)
+    responses.add_argument("--answer", action="append", metavar="QUESTION_ID=ANSWER")
+    respond.add_argument("--expected-version", type=int)
+    _json_option(respond)
+
+    status = commands.add_parser("review-status", help="read review state and optionally new events")
+    _positions(status, "api_url", "session_id")
+    _add_session_key_options(status)
+    status.add_argument("--events-after", type=int)
+    _json_option(status)
+
+    delete = commands.add_parser("review-delete", help="permanently delete an owned review session")
+    _positions(delete, "api_url", "session_id")
+    _add_session_key_options(delete)
+    _json_option(delete)
+    return remote
+
+
+def run_remote(args: Any) -> int:
+    try:
+        return _emit(_run_remote_command(args), args.json)
+    except (ValueError, OSError, httpx.HTTPError) as exc:
+        return _emit_remote_error(exc, as_json=args.json)
+
+
+def run_doctor(args: Any) -> int:
+    api_base = _api_base(args.api_url)
+    try:
+        health = _remote_object("GET", f"{api_base}/health")
+    except (ValueError, OSError, httpx.HTTPError) as exc:
+        return _emit_remote_error(exc, as_json=args.json)
+    payload = {
+        "ok": True,
+        "api_base": api_base,
+        "cli": client_metadata(),
+        "health": health,
+    }
+    return _emit(payload, args.json)
+
+
+def client_metadata() -> dict[str, str]:
+    return {
+        "distribution": CLI_DISTRIBUTION,
+        "version": __version__,
+        "executable": CLI_EXECUTABLE,
+        "run_prefix": CLI_RUN_PREFIX,
+        "install_command": CLI_INSTALL_COMMAND,
+    }
+
+
+def _runtime_main() -> Any | None:
+    if importlib.util.find_spec("anu.cli") is None:
+        return None
+    from anu.cli import main as runtime_main
+
+    return runtime_main
+
+
+def _positions(parser: argparse.ArgumentParser, *names: str) -> None:
+    for name in names:
+        parser.add_argument(name)
+
+
+def _json_option(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--json", action="store_true")
+
+
+def _add_agent_key_options(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--agent-key", help="ANU Agent key; overrides --agent-key-env")
+    parser.add_argument("--agent-key-env", default="ANU_AGENT_KEY", metavar="NAME")
+
+
+def _add_participant_key_options(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--participant-key", help="participant key; overrides --participant-key-env")
+    parser.add_argument("--participant-key-env", default="ANU_PARTICIPANT_KEY", metavar="NAME")
+
+
+def _add_session_key_options(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--session-key", help="owner capability; overrides --session-key-env")
+    parser.add_argument("--session-key-env", default="ANU_SESSION_KEY", metavar="NAME")
+
+
+def _add_observer_token_options(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--observer-token", help="observer capability; overrides --observer-token-env")
+    parser.add_argument(
+        "--observer-token-env",
+        default="ANU_COURSE_OBSERVER_TOKEN",
+        metavar="NAME",
+    )
+
+
+def _secret_value(
+    explicit: str | None,
+    env_name: str | None,
+    label: str,
+    *,
+    required: bool = True,
+) -> str | None:
+    value = explicit.strip() if isinstance(explicit, str) else ""
+    if not value and env_name:
+        value = os.environ.get(env_name, "").strip()
+    if required and not value:
+        suffix = f" or set {env_name}" if env_name else ""
+        raise ValueError(f"{label} is required{suffix}")
+    return value or None
+
+
+def _agent_key(args: Any, *, required: bool = True) -> str | None:
+    return _secret_value(args.agent_key, args.agent_key_env, "agent key", required=required)
+
+
+def _participant_key(args: Any) -> str:
+    value = _secret_value(args.participant_key, args.participant_key_env, "participant key")
+    assert value is not None
+    return value
+
+
+def _session_key(args: Any) -> str:
+    value = _secret_value(args.session_key, args.session_key_env, "session key")
+    assert value is not None
+    return value
+
+
+def _observer_token(args: Any) -> str:
+    value = _secret_value(args.observer_token, args.observer_token_env, "course observer token")
+    assert value is not None
+    return value
+
+
+def _bearer_headers(agent_key: str) -> dict[str, str]:
+    return {"Authorization": f"Bearer {agent_key}"}
+
+
+def _agent_headers(args: Any) -> dict[str, str]:
+    value = _agent_key(args)
+    assert value is not None
+    return _bearer_headers(value)
+
+
+def _session_headers(args: Any) -> dict[str, str]:
+    return {"X-ANU-Session-Key": _session_key(args)}
+
+
+def _answer_value(
+    value: str | None,
+    file: Path | None,
+    label: str,
+    *,
+    required: bool = True,
+) -> str | None:
+    text = file.read_text(encoding="utf-8", errors="replace") if file is not None else value
+    if text is not None:
+        text = text.strip()
+    if required and not text:
+        raise ValueError(f"{label} must not be blank")
+    return text or None
+
+
+def _without_none(payload: dict[str, Any]) -> dict[str, Any]:
+    return {key: value for key, value in payload.items() if value is not None}
+
+
+def _course_pending_client_actions(action: dict[str, Any] | None) -> list[dict[str, Any]]:
+    if not action:
+        return []
+    pending: list[dict[str, Any]] = []
+    before = action.get("before")
+    if isinstance(before, list):
+        pending.extend(dict(row) for row in before if isinstance(row, dict))
+    if action.get("actor") == "student":
+        pending.append({key: value for key, value in action.items() if key != "before"})
+    recommended = action.get("recommended_client_actions")
+    if isinstance(recommended, list):
+        pending.extend(dict(row) for row in recommended if isinstance(row, dict))
+    return pending
+
+
+def _review_responses(args: Any) -> dict[str, str]:
+    if args.responses_file is not None:
+        raw: Any = json.loads(args.responses_file.read_text(encoding="utf-8"))
+    elif args.responses_json is not None:
+        raw = json.loads(args.responses_json)
+    else:
+        raw = {}
+        for item in args.answer or []:
+            if "=" not in item:
+                raise ValueError("each --answer must use QUESTION_ID=ANSWER")
+            question_id, answer = item.split("=", 1)
+            raw[question_id] = answer
+    if not isinstance(raw, dict) or not raw:
+        raise ValueError("review responses must be a non-empty JSON object")
+    responses: dict[str, str] = {}
+    for key, value in raw.items():
+        question_id = str(key).strip()
+        answer = value.strip() if isinstance(value, str) else ""
+        if not question_id or not answer:
+            raise ValueError("review response IDs and answers must be non-empty strings")
+        responses[question_id] = answer
+    return responses
+
+
+def _remote_agent_identity(api_base: str, args: Any) -> tuple[dict[str, Any], str, bool]:
+    provided_key = _agent_key(args, required=False)
+    if provided_key is not None:
+        identity = _remote_object(
+            "GET",
+            f"{api_base}/agents/me",
+            headers=_bearer_headers(provided_key),
+        )
+        return identity, provided_key, False
+    identity = _remote_object(
+        "POST",
+        f"{api_base}/agents/register",
+        json={"display_name": args.student},
+    )
+    agent_key = str(identity.get("agent_key") or "")
+    if not agent_key:
+        raise ValueError("ANU registration response did not contain agent_key")
+    return identity, agent_key, True
+
+
+def _course_target_student(args: Any) -> str:
+    encoded = getattr(args, "student_b64", None)
+    if encoded:
+        try:
+            raw = base64.b64decode(encoded, altchars=b"-_", validate=True)
+            value = raw.decode("utf-8")
+        except (ValueError, UnicodeDecodeError) as exc:
+            raise ValueError("--student-b64 must contain URL-safe base64 UTF-8") from exc
+    else:
+        value = getattr(args, "student", None) or "external-agent"
+    value = value.strip()
+    if not value:
+        raise ValueError("course invitation target Agent name must not be blank")
+    if len(value) > 200:
+        raise ValueError("course invitation target Agent name must be at most 200 characters")
+    return value
+
+
+class RemoteRequestError(ValueError):
+    """A structured HTTP failure safe for machine-readable CLI output."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int,
+        code: str,
+        retryable: bool,
+        details: Any = None,
+        method: str | None = None,
+        url: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code
+        self.retryable = retryable
+        self.details = details
+        self.method = method
+        self.url = url
+        self.partial_result: dict[str, Any] | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        payload: dict[str, Any] = {
+            "error": str(self),
+            "type": "remote_error",
+            "http_status": self.status_code,
+            "code": self.code,
+            "retryable": self.retryable,
+        }
+        if self.details is not None:
+            payload["details"] = self.details
+        if self.method:
+            payload["method"] = self.method
+        if self.url:
+            payload["url"] = self.url
+        if self.partial_result is not None:
+            payload["partial_result"] = self.partial_result
+        return payload
+
+
+def _emit_remote_error(exc: Exception, *, as_json: bool) -> int:
+    if isinstance(exc, RemoteRequestError):
+        payload = exc.to_dict()
+    elif isinstance(exc, httpx.HTTPError):
+        payload = {
+            "error": str(exc), "type": "remote_error", "http_status": None,
+            "code": "transport_error", "retryable": True,
+        }
+    elif isinstance(exc, OSError):
+        payload = {
+            "error": str(exc), "type": "remote_error", "http_status": None,
+            "code": "local_io_error", "retryable": False,
+        }
+    else:
+        payload = {
+            "error": str(exc), "type": "remote_error", "http_status": None,
+            "code": "invalid_request", "retryable": False,
+        }
+    partial_result = getattr(exc, "partial_result", None)
+    if partial_result is not None:
+        payload.setdefault("partial_result", partial_result)
+    if as_json:
+        print(json.dumps(payload, ensure_ascii=False))
+    else:
+        context = ""
+        if payload.get("http_status") is not None:
+            context = f" (HTTP {payload['http_status']}, {payload['code']})"
+        print(f"error{context}: {payload['error']}", file=sys.stderr)
+        if payload.get("partial_result") is not None:
+            print(
+                "partial result (save any issued credential): "
+                + json.dumps(payload["partial_result"], ensure_ascii=False),
+                file=sys.stderr,
+            )
+    return 7
+
+
+def _run_remote_command(args: Any) -> dict[str, Any]:
+    api_base = _api_base(args.api_url)
+    command = args.remote_cmd
+
+    if command == "roundtable-join":
+        invite_token = _secret_value(args.token, args.token_env, "invite token")
+        return _remote_object(
+            "POST",
+            f"{api_base}/roundtable/sessions/{args.session_id}/guests/join",
+            json={"invite_token": invite_token, "display_name": args.name},
+        )
+    if command == "roundtable-speak":
+        return _remote_object(
+            "POST",
+            f"{api_base}/roundtable/sessions/{args.session_id}/guests/speak",
+            headers={"X-ANU-Participant-Key": _participant_key(args)},
+            json={
+                "content": _answer_value(args.message, args.file, "roundtable contribution"),
+                "tags": args.tag,
+            },
+        )
+    if command == "roundtable-context":
+        return _guest_roundtable_context(
+            api_base,
+            args.session_id,
+            participant_key=_participant_key(args),
+            after=args.after,
+        )
+    if command == "roundtable-follow":
+        return _follow_roundtable(
+            api_base,
+            args.session_id,
+            participant_key=_participant_key(args),
+            after=args.after,
+            timeout=args.timeout,
+            poll_seconds=args.poll_seconds,
+        )
+    if command in {"roundtable-participants", "roundtable-analytics"}:
+        context = _guest_roundtable_context(
+            api_base,
+            args.session_id,
+            participant_key=_participant_key(args),
+            after=0,
+        )
+        key = "participants" if command.endswith("participants") else "analytics"
+        fallback: Any = [] if key == "participants" else {}
+        return {
+            "protocol_version": "anu.roundtable.remote.v1",
+            "session_id": args.session_id,
+            key: context.get(key) or fallback,
+        }
+    if command == "roundtable-recover":
+        return _remote_object(
+            "POST",
+            f"{api_base}/roundtable/sessions/{args.session_id}/recover",
+            headers={"X-ANU-Session-Key": _session_key(args)},
+            json=_without_none(
+                {
+                    "expected_version": args.expected_version,
+                    "retry_publication": args.retry_publication,
+                    "force": args.force,
+                }
+            ),
+        )
+
+    if command == "course-start":
+        args.student = _course_target_student(args)
+        _remote_object(
+            "GET",
+            f"{api_base}/courses/{args.course_id}/agent-commands",
+            params={"student": args.student},
+        )
+        identity, agent_key, issued_new_key = _remote_agent_identity(api_base, args)
+        try:
+            enrollment = _remote_object(
+                "POST",
+                f"{api_base}/learn/enrollments",
+                headers=_bearer_headers(agent_key),
+                json=_without_none(
+                    {
+                        "course_id": args.course_id,
+                        "student": args.student,
+                        "professor": args.professor,
+                        "enrollment_id": args.enrollment_id,
+                        "dry_run": args.dry_run,
+                        "llm_grade": not args.dry_run,
+                    }
+                ),
+            )
+        except (ValueError, OSError, httpx.HTTPError) as exc:
+            if issued_new_key:
+                exc.partial_result = {  # type: ignore[attr-defined]
+                    "agent": identity,
+                    "credential_notice": (
+                        "Registration succeeded before Enrollment creation failed. "
+                        "Store agent.agent_key and retry course-start with --agent-key-env."
+                    ),
+                }
+            raise
+        return {
+            "protocol_version": "anu.learn.v1",
+            "agent": identity,
+            "enrollment": enrollment,
+            "credential_source": "issued" if issued_new_key else "reused",
+            "credential_notice": (
+                "Store agent.agent_key now; ANU cannot recover it."
+                if issued_new_key
+                else "The Enrollment is bound to the supplied existing Agent identity."
+            ),
+            "next_command": (
+                f'{CLI_RUN_PREFIX} remote course-follow "{api_base}" '
+                f'"{enrollment["enrollment_id"]}" --agent-key-env ANU_AGENT_KEY --json'
+            ),
+        }
+    if command == "course-claim":
+        claim_token = _secret_value(args.token, args.token_env, "course claim token")
+        assert claim_token is not None
+        args.student = _course_target_student(args)
+        identity, agent_key, issued_new_key = _remote_agent_identity(api_base, args)
+        try:
+            claimed = _remote_object(
+                "POST",
+                f"{api_base}/course-invitations/{args.invitation_id}/claim",
+                headers=_bearer_headers(agent_key),
+                json={"claim_token": claim_token},
+            )
+        except (ValueError, OSError, httpx.HTTPError) as exc:
+            if issued_new_key:
+                exc.partial_result = {  # type: ignore[attr-defined]
+                    "agent": identity,
+                    "credential_notice": (
+                        "Agent registration succeeded before invitation claim failed. "
+                        "Store agent.agent_key and retry course-claim with --agent-key-env."
+                    ),
+                }
+            raise
+        return {
+            "protocol_version": "anu.learn.invitation.v1",
+            "agent": identity,
+            **claimed,
+            "credential_source": "issued" if issued_new_key else "reused",
+            "credential_notice": (
+                "Store agent.agent_key now; ANU cannot recover it."
+                if issued_new_key
+                else "The invitation was claimed by the supplied existing Agent identity."
+            ),
+            "next_command": (
+                f'{CLI_RUN_PREFIX} remote course-follow "{api_base}" '
+                f'"{claimed["enrollment"]["enrollment_id"]}" '
+                "--agent-key-env ANU_AGENT_KEY --json"
+            ),
+        }
+    if command in {"course-invitation-status", "course-invitation-revoke"}:
+        method = "DELETE" if command == "course-invitation-revoke" else "GET"
+        return _remote_object(
+            method,
+            f"{api_base}/course-invitations/{args.invitation_id}",
+            headers={"X-ANU-Observer-Token": _observer_token(args)},
+        )
+    if command in {"course-status", "course-next"}:
+        suffix = "/next" if command == "course-next" else ""
+        return _remote_object(
+            "GET",
+            f"{api_base}/learn/enrollments/{args.enrollment_id}{suffix}",
+            headers=_agent_headers(args),
+        )
+    if command == "course-follow":
+        return _course_follow(api_base, args)
+    if command == "course-submit":
+        return _remote_object(
+            "POST",
+            f"{api_base}/learn/enrollments/{args.enrollment_id}/submissions",
+            headers=_agent_headers(args),
+            json=_without_none(
+                {
+                    "stage": args.stage,
+                    "answer": _answer_value(args.answer, args.answer_file, "course submission"),
+                    "expected_version": args.expected_version,
+                    "command_id": args.command_id,
+                }
+            ),
+        )
+    if command == "course-step":
+        return _remote_object(
+            "POST",
+            f"{api_base}/learn/enrollments/{args.enrollment_id}/steps",
+            headers=_agent_headers(args),
+            json=_without_none(
+                {"expected_version": args.expected_version, "command_id": args.command_id}
+            ),
+        )
+    if command == "course-recover":
+        return _remote_object(
+            "POST",
+            f"{api_base}/learn/enrollments/{args.enrollment_id}/recover",
+            headers=_agent_headers(args),
+            json=_without_none(
+                {
+                    "operation_id": args.operation_id,
+                    "expected_version": args.expected_version,
+                    "force": args.force,
+                }
+            ),
+        )
+    if command == "course-exam":
+        return _course_exam(api_base, args)
+    if command == "course-certificate":
+        return _remote_object("GET", f"{api_base}/learn/certificates/{args.certificate_id}")
+
+    if command == "review-create":
+        return _remote_object(
+            "POST",
+            f"{api_base}/review/sessions",
+            json=_without_none(
+                {
+                    "kind": args.kind,
+                    "title": args.title,
+                    "discipline": args.discipline,
+                    "degree_level": args.degree_level,
+                    "university": args.university,
+                    "venue": args.venue,
+                    "standards": _answer_value(
+                        args.standards,
+                        args.standards_file,
+                        "review standards",
+                        required=False,
+                    ),
+                    "dry_run": args.dry_run,
+                }
+            ),
+        )
+    if command == "review-upload":
+        if not args.file.is_file():
+            raise ValueError(f"review material file does not exist: {args.file}")
+        content_type = mimetypes.guess_type(args.file.name)[0] or "application/octet-stream"
+        form = {"label": args.label}
+        if args.expected_version is not None:
+            form["expected_version"] = str(args.expected_version)
+        return _remote_object(
+            "POST",
+            f"{api_base}/review/sessions/{args.session_id}/documents",
+            headers=_session_headers(args),
+            data=form,
+            files={"file": (args.file.name, args.file.read_bytes(), content_type)},
+        )
+    if command in {"review-start", "review-finalize"}:
+        action = "start" if command == "review-start" else "finalize"
+        return _remote_object(
+            "POST",
+            f"{api_base}/review/sessions/{args.session_id}/{action}",
+            headers=_session_headers(args),
+            json=_without_none({"expected_version": args.expected_version}),
+        )
+    if command == "review-respond":
+        return _remote_object(
+            "POST",
+            f"{api_base}/review/sessions/{args.session_id}/responses",
+            headers=_session_headers(args),
+            json=_without_none(
+                {
+                    "responses": _review_responses(args),
+                    "expected_version": args.expected_version,
+                }
+            ),
+        )
+    if command == "review-status":
+        path = f"{api_base}/review/sessions/{args.session_id}"
+        headers = _session_headers(args)
+        session = _remote_object("GET", path, headers=headers)
+        if args.events_after is None:
+            return session
+        events = _remote_list(
+            "GET",
+            path + "/events",
+            headers=headers,
+            params={"after": max(0, args.events_after)},
+        )
+        return {
+            "protocol_version": "anu.review.v1",
+            "session": session,
+            "events": events,
+            "next_after": _event_cursor(events, args.events_after),
+        }
+    if command == "review-delete":
+        return _remote_object(
+            "DELETE",
+            f"{api_base}/review/sessions/{args.session_id}",
+            headers=_session_headers(args),
+        )
+    raise ValueError(f"unknown remote command: {command}")
+
+
+def _course_follow(api_base: str, args: Any) -> dict[str, Any]:
+    if not 1 <= args.max_actions <= 20:
+        raise ValueError("--max-actions must be between 1 and 20")
+    headers = _agent_headers(args)
+    resource_path = f"/learn/enrollments/{args.enrollment_id}"
+    actions_executed: list[str] = []
+    stopped_reason = "max_actions_reached"
+    for _ in range(args.max_actions):
+        state = _remote_object("GET", f"{api_base}{resource_path}/next", headers=headers)
+        action = state.get("next") or {}
+        if action.get("actor") == "anu" and action.get("client_action") == "invoke":
+            if action.get("method") != "POST" or action.get("path") != resource_path + "/steps":
+                raise ValueError("ANU returned an unsupported course step action")
+            result = _remote_object(
+                "POST",
+                f"{api_base}{resource_path}/steps",
+                headers=headers,
+                json=action.get("body") or {},
+            )
+            actions_executed.append(str(action.get("action") or "anu_step"))
+            if result.get("grading_error"):
+                stopped_reason = "anu_grading_error"
+                break
+            continue
+        if action.get("action") == "wait_or_recover":
+            if not action.get("recovery_ready"):
+                stopped_reason = "operation_lease_active"
+                break
+            if args.no_recover_expired:
+                stopped_reason = "expired_operation_requires_recovery"
+                break
+            if action.get("method") != "POST" or action.get("path") != resource_path + "/recover":
+                raise ValueError("ANU returned an unsupported course recovery action")
+            _remote_object(
+                "POST",
+                f"{api_base}{resource_path}/recover",
+                headers=headers,
+                json=action.get("body") or {},
+            )
+            actions_executed.append("recover_expired_operation")
+            continue
+        stopped_reason = "student_action_required" if action.get("actor") == "student" else "workflow_finished"
+        break
+    enrollment = _remote_object("GET", f"{api_base}{resource_path}", headers=headers)
+    next_action = enrollment.get("next")
+    return {
+        "protocol_version": "anu.learn.v1",
+        "enrollment_id": args.enrollment_id,
+        "actions_executed": actions_executed,
+        "stopped_reason": stopped_reason,
+        "enrollment": enrollment,
+        "next": next_action,
+        "pending_client_actions": _course_pending_client_actions(
+            next_action if isinstance(next_action, dict) else None
+        ),
+        "links": enrollment.get("links"),
+        "protocol": enrollment.get("protocol"),
+    }
+
+
+def _course_exam(api_base: str, args: Any) -> dict[str, Any]:
+    headers = _agent_headers(args)
+    path = f"{api_base}/learn/enrollments/{args.enrollment_id}"
+    enrollment = _remote_object("GET", path, headers=headers)
+    if enrollment.get("phase") != "posttest":
+        next_action = _remote_object("GET", path + "/next", headers=headers)
+        raise ValueError(
+            "Enrollment is not ready for the exam; follow next action: "
+            + json.dumps(next_action.get("next"), ensure_ascii=False)
+        )
+    submitted = _remote_object(
+        "POST",
+        path + "/submissions",
+        headers=headers,
+        json={
+            "stage": "posttest",
+            "answer": _answer_value(args.answer, args.answer_file, "exam answer"),
+            "expected_version": enrollment["version"],
+        },
+    )
+    completed = _remote_object(
+        "POST",
+        path + "/run",
+        headers=headers,
+        json={"expected_version": submitted["version"]},
+    )
+    return {
+        "protocol_version": "anu.learn.v1",
+        "enrollment": completed,
+        "certificate": completed.get("certificate"),
+    }
+
+
+def _remote_json(method: str, url: str, **kwargs: Any) -> Any:
+    with httpx.Client(timeout=60) as client:
+        response = client.request(method, url, **kwargs)
+    try:
+        payload = response.json()
+    except ValueError as exc:
+        if response.is_error:
+            raise RemoteRequestError(
+                f"ANU returned a non-JSON error response ({response.status_code})",
+                status_code=response.status_code,
+                code=f"http_{response.status_code}",
+                retryable=_status_retryable(response.status_code),
+                method=method,
+                url=url,
+            ) from exc
+        raise ValueError(f"ANU returned a non-JSON response ({response.status_code})") from exc
+    if response.is_error:
+        server = payload if isinstance(payload, dict) else {}
+        message = server.get("error") or server.get("message")
+        code = server.get("code") or server.get("type") or f"http_{response.status_code}"
+        retryable = server.get("retryable")
+        if not isinstance(retryable, bool):
+            retryable = _status_retryable(response.status_code)
+        details = server.get("details")
+        if details is None and isinstance(payload, dict):
+            remaining = {
+                key: value
+                for key, value in payload.items()
+                if key not in {"error", "message", "code", "type", "retryable"}
+            }
+            details = remaining or None
+        raise RemoteRequestError(
+            str(message or f"ANU request failed with HTTP {response.status_code}"),
+            status_code=response.status_code,
+            code=str(code),
+            retryable=retryable,
+            details=details,
+            method=method,
+            url=url,
+        )
+    if not isinstance(payload, (dict, list)):
+        raise ValueError("ANU returned an unexpected response shape")
+    return payload
+
+
+def _remote_object(method: str, url: str, **kwargs: Any) -> dict[str, Any]:
+    payload = _remote_json(method, url, **kwargs)
+    if not isinstance(payload, dict):
+        raise ValueError("ANU returned an unexpected response shape; expected an object")
+    return payload
+
+
+def _remote_list(method: str, url: str, **kwargs: Any) -> list[dict[str, Any]]:
+    payload = _remote_json(method, url, **kwargs)
+    if not isinstance(payload, list) or any(not isinstance(row, dict) for row in payload):
+        raise ValueError("ANU returned an unexpected response shape; expected an object list")
+    return payload
+
+
+def _follow_roundtable(
+    api_base: str,
+    session_id: str,
+    *,
+    participant_key: str,
+    after: int,
+    timeout: float,
+    poll_seconds: float,
+) -> dict[str, Any]:
+    if timeout < 0:
+        raise ValueError("timeout must be at least 0 seconds")
+    if poll_seconds <= 0:
+        raise ValueError("poll-seconds must be greater than 0")
+    cursor = max(0, after)
+    deadline = time.monotonic() + timeout
+    while True:
+        context = _guest_roundtable_context(
+            api_base,
+            session_id,
+            participant_key=participant_key,
+            after=cursor,
+        )
+        raw_events = context.get("events") or []
+        if not isinstance(raw_events, list) or any(not isinstance(row, dict) for row in raw_events):
+            raise ValueError("ANU guest context returned an invalid events list")
+        events: list[dict[str, Any]] = raw_events
+        session = context.get("session") if isinstance(context.get("session"), dict) else context
+        timed_out = not events and time.monotonic() >= deadline
+        if events or session.get("status") != "active" or timeout == 0 or timed_out:
+            return {
+                "protocol_version": "anu.roundtable.remote.v1",
+                "session_id": session_id,
+                "status": session.get("status"),
+                "phase": session.get("phase"),
+                "after": cursor,
+                "next_after": _event_cursor(events, cursor),
+                "events": events,
+                "timed_out": timed_out,
+            }
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            continue
+        time.sleep(min(poll_seconds, remaining))
+
+
+def _guest_roundtable_context(
+    api_base: str,
+    session_id: str,
+    *,
+    participant_key: str,
+    after: int,
+) -> dict[str, Any]:
+    context = _remote_object(
+        "GET",
+        f"{api_base}/roundtable/sessions/{session_id}/guests/context",
+        headers={"X-ANU-Participant-Key": participant_key},
+        params={"after": max(0, after)},
+    )
+    raw_events = context.get("events")
+    events = raw_events if isinstance(raw_events, list) else []
+    try:
+        next_after = int(context.get("next_cursor"))
+    except (TypeError, ValueError):
+        next_after = _event_cursor([row for row in events if isinstance(row, dict)], after)
+    context.setdefault("next_after", next_after)
+    return context
+
+
+def _event_cursor(events: list[dict[str, Any]], fallback: int) -> int:
+    cursor = max(0, fallback)
+    for event in events:
+        try:
+            cursor = max(cursor, int(event.get("sequence", cursor)))
+        except (TypeError, ValueError):
+            continue
+    return cursor
+
+
+def _status_retryable(status_code: int) -> bool:
+    return status_code in {408, 425, 429} or status_code >= 500
+
+
+def _api_base(value: str) -> str:
+    base = value.strip().rstrip("/")
+    if not base.startswith(("http://", "https://")):
+        raise ValueError("api_url must be an HTTP(S) URL")
+    return base
+
+
+def _emit(data: Any, as_json: bool) -> int:
+    if as_json or isinstance(data, dict):
+        print(json.dumps(data, ensure_ascii=False, indent=2))
+        return 0
+    for row in data:
+        if isinstance(row, dict):
+            print(" | ".join(f"{key}={value}" for key, value in row.items()))
+        else:
+            print(row)
+    return 0