elan-cli 0.1.0__py3-none-any.whl

elan_cli/env.py

@@ -0,0 +1,96 @@
+"""`elan env` — the local environment `elan validate` needs.
+
+WHY THIS COMMAND EXISTS AT ALL.
+
+Checking `elan.yaml` against the Python MANIFESTs means IMPORTING the repo's
+agents, which needs the platform runtime — `agentkit_runtime`, `agentkit_core`
+and whatever ADK pulls in. The CLI deliberately does not carry those: it would
+put a web server and a database driver on the machine for a command that reads
+files. So the runtime goes in a `.venv` beside `elan.yaml`, and this is what
+puts it there.
+
+IT USED TO COME FROM A CHECKOUT OF THE PLATFORM MONOREPO, through `--runtime`
+and `$ELAN_RUNTIME_SRC`, because the agentkit packages went from that repo
+straight into the base image and were published to no index — so there was no
+`pip install` that would work. There is now (ADR-0220): one name,
+`elan-agentkit-runtime`, with core and plugins as its dependencies, which is
+the same single `--package` the runtime image syncs.
+
+THIS MODULE'S OWN DOCSTRING USED TO PREDICT ITS DELETION — "when they are
+published, this command goes away and the scaffolded repo grows an ordinary
+dependency instead" — and that was wrong about the destination. A scaffolded
+repo deliberately has NO `pyproject.toml`; the one it may grow is for libraries
+BEYOND the runtime, and its own README says "Never put `agentkit-*` in it". That
+file is what the BUILD installs, and the build's image already carries the
+runtime, so declaring it there would install it twice with no guarantee the two
+versions agree. The command stays; only where it resolves from changed.
+
+UNPINNED, AND THAT IS A DECISION. Every package here carries its own version, so
+pinning the runtime to the CLI's would couple two numbers meant to move apart.
+The real answer is version negotiation, which this CLI has none of — no
+`--version`, no `User-Agent`, nothing in the handshake — and which is its own
+change.
+
+IT STILL DOES NOT TOUCH THE DEPLOY FILE, which remains the part worth being
+careful about: the environment lives in `.venv` and is described nowhere the
+builder reads.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from pathlib import Path
+
+from elan_cli.project import ProjectError, find
+
+#: What `elan validate` and `elan adk` import the repo's agents through.
+#:
+#: ONE NAME, NOT THREE. `elan-agentkit-core` and `elan-agentkit-plugins` are its
+#: dependencies, so naming all three here would be three chances to disagree
+#: with the manifest that already relates them.
+RUNTIME_PACKAGE = "elan-agentkit-runtime"
+
+
+def run(start: Path | None = None) -> int:
+    try:
+        project = find(start)
+    except ProjectError as exc:
+        print(f"error: {exc}")
+        return 2
+
+    if not shutil.which("uv"):
+        print("error: `uv` is not on PATH, and this uses it to build the\n"
+              "project's environment. https://docs.astral.sh/uv/")
+        return 2
+
+    venv = project.root / ".venv"
+    python = venv / "bin" / "python"
+    print(f"environment  {venv}")
+    # FLUSHED BECAUSE A SUBPROCESS IS ABOUT TO WRITE TO THE SAME TERMINAL.
+    # Python buffers when its output is a pipe and uv writes straight to the
+    # descriptor, so without this the heading appears BELOW the wall of
+    # package names it is meant to introduce.
+    print(f"runtime      {RUNTIME_PACKAGE}", flush=True)
+
+    if not python.exists():
+        if _uv(["venv", str(venv)], project.root) != 0:
+            return 1
+
+    if _uv(["pip", "install", "--python", str(python), RUNTIME_PACKAGE],
+           project.root) != 0:
+        return 1
+
+    print()
+    print("ok — `elan validate` will find this automatically.")
+    return 0
+
+
+def _uv(args: list[str], cwd: Path) -> int:
+    """Run uv, letting its own output through.
+
+    NOT CAPTURED. A resolution failure here is about the developer's machine —
+    a Python version, a compiler, a network — and uv says all of that far
+    better than a wrapper repeating "install failed" would.
+    """
+    return subprocess.run(["uv", *args], cwd=cwd).returncode

elan_cli/files.py

@@ -0,0 +1,166 @@
+"""`elan files` — the artifacts an agent reads and writes.
+
+WHY A CLI SURFACE AT ALL. Three things people actually do from a terminal:
+upload the project's policy document once so every agent can read it, pull a
+file an agent produced while debugging why it looks wrong, and list what a
+conversation has accumulated. The alternative was `curl` with a hand-built
+bearer and a hand-assembled signed PUT — four exact headers, one of which
+pins the byte length.
+
+THE BYTES GO STRAIGHT TO STORAGE, NEVER THROUGH THE PLATFORM. `upload` asks the
+platform to authorise one transfer and then PUTs to the URL it gets back; the
+PUT carries NO platform token, because that URL is Google's host and a bearer
+there would be a credential sent to a third party in a request that succeeds.
+
+THE SCOPE COMES FROM THE FILENAME, not from a flag, because that is how the
+agent's own `load_artifact` addresses it — so a name that works here works
+unchanged in a tool. `elan_agentkit_contracts.artifacts` is the one place the
+table lives (ADR-0116); nothing here restates it.
+
+NO `--tenant`, for the same reason as `elan wallet`: every route derives it from
+the verified token, so a flag would be a value the service ignores.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import httpx
+from elan_agentkit_contracts.artifacts import (
+    MAX_ARTIFACT_BYTES,
+    SHARED_SCOPES,
+    ArtifactNameRefused,
+    scope_of,
+    validate_artifact_filename,
+)
+
+from elan_cli.client import Api
+from elan_cli.project import ProjectError, find
+
+
+class FilesError(Exception):
+    """Phrased for the developer running the command."""
+
+
+def _project(api: Api, given: str) -> str:
+    """The project, from the flag or from the elan.yaml you are standing in."""
+    if given:
+        return given
+    try:
+        return find().project
+    except ProjectError as exc:
+        raise FilesError(
+            "which project? Run this inside a project directory, or pass "
+            "--project."
+        ) from exc
+
+
+def _checked(filename: str) -> str:
+    try:
+        validate_artifact_filename(filename)
+    except ArtifactNameRefused as exc:
+        raise FilesError(str(exc)) from exc
+    return filename
+
+
+def _common(args, api: Api) -> dict:
+    return {"target_slug": args.target, "project": _project(api, args.project),
+            "user": getattr(args, "user", "") or ""}
+
+
+def ls(args, api: Api) -> int:
+    """What this conversation can see, prefixes intact."""
+    answer = api.request("GET", "/v1/artifacts", params={
+        **_common(args, api), "session_id": args.session})
+    names = answer.get("artifacts", [])
+    if not names:
+        print("no files")
+        return 0
+    # GROUPED BY SCOPE, because the prefix is the only thing distinguishing a
+    # project document from a file in this one conversation, and a flat list
+    # buries that in punctuation.
+    for name in names:
+        scope, bare = scope_of(name)
+        shared = " (read-only)" if scope in SHARED_SCOPES else ""
+        print(f"  {scope:<8} {bare}{shared}")
+    return 0
+
+
+def get(args, api: Api) -> int:
+    """Download one file.
+
+    THE PLATFORM ANSWERS WITH A URL AND NOT WITH BYTES, so this follows it —
+    and deliberately with a plain client carrying no token, because the URL is
+    storage's and the signature is the whole authorisation.
+    """
+    _checked(args.filename)
+    answer = api.request("GET", "/v1/artifacts/download", params={
+        **_common(args, api), "session_id": args.session,
+        "filename": args.filename,
+        **({"version": args.version} if args.version is not None else {})})
+
+    destination = Path(args.out) if args.out else Path(
+        scope_of(args.filename)[1].rsplit("/", 1)[-1])
+    try:
+        with httpx.Client(timeout=300.0, follow_redirects=True) as client:
+            response = client.get(answer["url"])
+            response.raise_for_status()
+    except httpx.HTTPError as exc:
+        raise FilesError(f"could not download {args.filename}: {exc}") from exc
+    destination.write_bytes(response.content)
+    print(f"{destination} ({len(response.content)} bytes)")
+    return 0
+
+
+def put(args, api: Api) -> int:
+    """Upload one file to a scope.
+
+    THE SIZE IS THE AUTHORISATION. It is signed into the URL as an exact range,
+    so this reads the file first and declares its real length — a declared
+    guess would be refused by storage rather than truncated.
+    """
+    source = Path(args.path)
+    if not source.is_file():
+        raise FilesError(f"{source} is not a file")
+    payload = source.read_bytes()
+    if not payload:
+        raise FilesError(f"{source} is empty; there is nothing to store")
+    if len(payload) > MAX_ARTIFACT_BYTES:
+        raise FilesError(
+            f"{source} is {len(payload)} bytes; the limit is "
+            f"{MAX_ARTIFACT_BYTES} ({MAX_ARTIFACT_BYTES // (1024 * 1024)} MiB)")
+
+    name = _checked(args.name or source.name)
+    scope, _ = scope_of(name)
+    answer = api.request("POST", "/v1/artifacts/uploads", json={
+        **_common(args, api), "session_id": args.session, "filename": name,
+        "content_type": args.content_type, "size": len(payload)})
+
+    try:
+        with httpx.Client(timeout=300.0) as client:
+            # EXACTLY THE HEADERS WE WERE GIVEN, and no Authorization. Each one
+            # is part of what was signed; adding ours would break the signature
+            # and the error would name the signature rather than the header.
+            response = client.request(
+                answer["method"], answer["url"], content=payload,
+                headers=answer["headers"])
+            response.raise_for_status()
+    except httpx.HTTPError as exc:
+        raise FilesError(
+            f"the bytes did not reach storage: {exc}. The signed URL pins the "
+            f"exact size ({len(payload)}) and content type "
+            f"({args.content_type}) that were declared."
+        ) from exc
+
+    print(f"{name}  version {answer['version']}  {scope} scope")
+    return 0
+
+
+def rm(args, api: Api) -> int:
+    """Remove one file and every version of it."""
+    _checked(args.filename)
+    api.request("DELETE", "/v1/artifacts", params={
+        **_common(args, api), "session_id": args.session,
+        "filename": args.filename})
+    print(f"removed {args.filename}")
+    return 0

elan_cli/invoke.py

@@ -0,0 +1,196 @@
+"""`elan invoke` — send an agent a message and read what it says back.
+
+THE FIRST THING SOMEBODY WANTS AFTER A DEPLOY, and until now the only way to
+do it was a Python script run by whoever had a shell on the platform. A deploy
+that succeeds and cannot be exercised is a deploy nobody can believe.
+
+IT HOLDS A SOCKET RATHER THAN POLLING THE TRANSCRIPT, and this docstring used
+to say the opposite with a reasoned argument whose premise was false: ADK
+persists a conversation to the AGENT'S OWN database (ADR-0036) while rt-service
+holds the PLATFORM's, so that route answers "nothing here" correctly and for
+ever for every tenant.
+
+EVERY RULE ABOUT THE STREAM COMES FROM `elan_sdk` (ADR-0116) — what ends a run,
+what is a control frame, where the text is, who spoke. This file owns the
+PRINTING and nothing else, because the one rule it owned for itself had drifted
+into a hang: it waited for `finished`, which a paused run never sends.
+
+THE FIRST REPLY CAN TAKE MINUTES AND THAT IS NOT A BUG. An agent scaled to
+zero needs a KEDA poll, a node, a sandboxed container start and an ADK import
+before it reads its queue. The wait message says so, because silence for two
+minutes reads as a failure.
+"""
+
+from __future__ import annotations
+
+import sys
+import time
+import uuid
+
+from elan_cli.client import Api, ApiError
+from elan_cli.stream import (
+    SHOWN,
+    StreamError,
+    author_of,
+    ends_the_run,
+    replies,
+    text_of,
+    watching,
+)
+
+#: Long enough for a cold start with a scale-from-zero and a model call.
+DEFAULT_TIMEOUT = 300.0
+
+#: What answers each kind of pause, because THIS COMMAND CANNOT. A pause can
+#: outlast any command — the push handler acks at the pause and resumption
+#: arrives as a new message — which is why resuming is an API call and not a
+#: flag here. There is no `elan resume` subcommand, so every one of these names
+#: something that exists elsewhere, checked against the subparsers and the
+#: routes rather than written from memory.
+ANSWERED_BY = {
+    "input": ("a node is waiting for a VALUE — `elan.runtime.resume(id, "
+              "approved=True, payload={...})`, or POST /v1/invocations/{id}"
+              "/resume"),
+    "confirmation": ("a tool is waiting for APPROVAL — the console's approvals "
+                     "page, or `elan.actions.decide_batch(...)`"),
+    "tool": ("a long-running tool is waiting for YOUR backend's RESULT — "
+             "`elan.tools.submit(call_id, result={...})`"),
+}
+
+
+def run(api: Api, target: str, text: str, *, session: str = "",
+        project: str = "", timeout: float = DEFAULT_TIMEOUT,
+        now=time.monotonic, open_socket=None) -> int:
+    """Send one message and print what comes back. Returns the exit code.
+
+    THE CLOCK IS INJECTED so a timeout can be reached without waiting for one.
+    The `sleep` that used to sit beside it is gone with the polling loop it
+    belonged to: nothing here sleeps any more, it blocks on a socket, and a
+    parameter no code path reads is a seam that lies about how this works.
+    """
+    session_id = session or f"cli-{uuid.uuid4().hex[:12]}"
+
+    # ── SUBSCRIBE FIRST, THEN INVOKE ────────────────────────────────────
+    #
+    # Pub/Sub discards a message published to a topic with no subscription,
+    # and rt-service creates a tenant's subscription when its FIRST socket
+    # opens. Invoking before connecting therefore loses everything published
+    # in between — on a warm agent, that is the entire reply.
+    #
+    # THE TRANSCRIPT CANNOT BE POLLED INSTEAD, which is what this replaced.
+    # ADK writes a conversation to the AGENT'S OWN database (ADR-0036) and
+    # rt-service holds the PLATFORM's, so that read answers "nothing here"
+    # correctly and forever for every tenant.
+    try:
+        with watching(api.config.api, api.token(), session_id,
+                      open_socket=open_socket) as socket:
+            try:
+                started = api.request("POST", "/v1/invocations", json={
+                    "target_slug": target, "text": text,
+                    "session_id": session_id, "project": project})
+            except ApiError as exc:
+                print(f"{exc}", file=sys.stderr)
+                return 1
+
+            invocation = started.get("invocation_id", "")
+            print(f"invocation {invocation}")
+            print(f"session     {session_id}")
+            print()
+            return _follow(socket, invocation, target, session_id,
+                           timeout, now)
+    except StreamError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+
+def _follow(socket, invocation: str, target: str, session_id: str,
+            timeout: float, now) -> int:
+    """Print what happens until the run ends. Returns the exit code."""
+    deadline = now() + timeout
+    said = False
+    #: True when the run reached a terminal event rather than running out of
+    #: time. The difference is the whole message below.
+    ended = False
+    #: The interrupt kind, when the run STOPPED TO ASK rather than finishing.
+    #: A third outcome, and it used to be unreachable: this waited for
+    #: `finished`, which a paused run never sends, so it blocked in `recv()`
+    #: for ever on a run that was sitting there asking a question (ADR-0116).
+    waiting_on = ""
+    for event in replies(socket, invocation):
+        if ends_the_run(event):
+            # ASKED OF THE SDK, which is the only place the rule is spelled —
+            # `finished`, `error`, OR the engine's terminal pause.
+            ended = True
+            if event.get("kind") == "paused":
+                waiting_on = str(
+                    (event.get("payload") or {}).get("interrupt_kind") or "?")
+        kind = event.get("kind")
+        if kind == "queued":
+            # THE ONE EVENT rt-service SENDS ITSELF, because a scaled-to-zero
+            # agent has no pod to send it. Saying so is what stops the wait
+            # reading as a hang.
+            print("  queued — a sleeping agent is scheduled and started "
+                  "before it reads its queue; the first reply after a quiet "
+                  "period is the slow one.")
+            continue
+        if kind not in SHOWN:
+            continue
+        body = text_of(event)
+        if not body:
+            continue
+        if kind == "error":
+            print(f"\nerror: {body}", file=sys.stderr)
+            return 1
+        # WHO SPOKE, when a run has more than one agent in it. Falls back to
+        # the target, which is the only name a single-agent run has.
+        who = author_of(event) or target
+        print(f"{who}: {body}" if not said else body)
+        said = True
+        if now() > deadline:
+            break
+    # ── PAUSED IS NOT FINISHED, AND IT IS NOT SILENCE EITHER ───────────────
+    #
+    # It is the third outcome, and the one this command cannot act on. Said
+    # before the exit code is decided because a run can both answer and then
+    # pause — asking a follow-up question is the commonest shape of all — and
+    # a note is the right weight for that, where a failure would not be.
+    if waiting_on:
+        # A NEWER ENGINE MAY PAUSE FOR A REASON THIS CLI HAS NOT HEARD OF, and
+        # the honest answer then is the kind's own name plus the read path —
+        # not a bare token the reader has to guess at.
+        answer = ANSWERED_BY.get(
+            waiting_on, f"{waiting_on} — a pause kind this CLI does not know")
+        print(f"\n{target} is PAUSED, not finished.\n"
+              f"  invocation  {invocation}\n"
+              f"  waiting on  {answer}\n"
+              f"`elan invoke` cannot answer a pause: a pause can outlast any "
+              f"command, which is why resuming is an API call. `elan.runs."
+              f"get({invocation!r})` reads what it has done so far.",
+              file=sys.stderr)
+
+    if said:
+        return 0
+
+    # WHICH SILENCE THIS WAS, because they need different reactions and the
+    # message used to claim the wrong one. `No reply within 300s` was printed
+    # the instant a run ENDED having said nothing — so a command that returned
+    # in two seconds reported a five-minute timeout, and the reader went
+    # looking for something slow.
+    if waiting_on:
+        print("It paused without saying anything first, so the question is in "
+              "the run rather than above.", file=sys.stderr)
+    elif ended:
+        print(f"\n{target} finished without saying anything. That is the "
+              "agent's own behaviour rather than a timeout — check its logs, "
+              "and check it returns content from `build()`.", file=sys.stderr)
+    else:
+        # NOT `--session` HERE, WHICH IS WHAT THIS USED TO SAY: `--text` is
+        # REQUIRED, so "rejoins the same conversation without sending anything
+        # new" named a command argparse refuses. Nothing buffers for a closed
+        # socket either, so reconnecting would show only what happens NEXT —
+        # the read path is the one P2 built for exactly this.
+        print(f"\nNo reply within {timeout:.0f}s. The invocation was accepted "
+              f"and may still be running — `elan.runs.get({invocation!r})`, or "
+              f"GET /v1/runs/{invocation}, reads what it has done so far.",
+              file=sys.stderr)
+    return 1

elan_cli/logs.py

@@ -0,0 +1,149 @@
+"""`elan logs` — what a build said, and what a running workload is saying.
+
+TWO KINDS OF LOG, AND THE COMMAND USED TO MEAN ONLY ONE. A failed build's
+`logUrl` points at Cloud Build's console in the PLATFORM's project, which an
+external customer cannot open — so the only actionable part of a build failure
+was a link that answered "permission denied". That is `elan logs <deployment>`.
+
+Once an agent is RUNNING, the question changes and the old command could not
+answer it: a developer whose agent is misbehaving wants its stdout, and got a
+build transcript. `elan logs --workload <name>` is that, and it reads the same
+route the console does.
+
+THE FLAG RATHER THAN A SECOND COMMAND, because "logs" is the word a person
+reaches for either way. A separate `elan workload logs` would mean guessing
+which one they meant every time they typed the shorter thing.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from elan_cli.client import Api, ApiError
+
+#: Printed when `--tail` is given without a number.
+DEFAULT_TAIL = 50
+
+
+def run(api: Api, deployment_id: str, *, tail: int = 0) -> int:
+    try:
+        payload = api.request("GET", f"/v1/deployments/{deployment_id}/logs")
+    except ApiError as exc:
+        print(f"{exc}", file=sys.stderr)
+        return 1
+
+    note = payload.get("note")
+    if note:
+        # NOT AN ERROR. A deploy refused at validate never started a build, and
+        # saying so beats printing an empty log that reads as a fetch failure.
+        print(note)
+        return 0
+
+    log = payload.get("log") or ""
+    if not log.strip():
+        print("The build produced no output, which usually means it was "
+              "cancelled before it started.")
+        return 0
+
+    lines = log.splitlines()
+    if tail and len(lines) > tail:
+        print(f"[showing the last {tail} of {len(lines)} lines]")
+        lines = lines[-tail:]
+    print("\n".join(lines))
+    return 0
+
+
+def workload(api: Api, name: str, *, project: str, minutes: int = 60,
+             probes: bool = False, tail: int = 0) -> int:
+    """What a running workload has said.
+
+    THE PROJECT IS REQUIRED and the service refuses without it. An agent slug is
+    unique within a PROJECT, not within a tenant, so two projects may both run
+    `worker` — and guessing which would be a coin toss over whose log to print.
+    """
+    if not project:
+        print("Name the project this workload belongs to: `--project <slug>`.\n"
+              "A workload name is unique within a project, not within a tenant.",
+              file=sys.stderr)
+        return 2
+
+    query = f"?project={project}&since_minutes={minutes}"
+    if probes:
+        query += "&probes=true"
+    try:
+        payload = api.request("GET", f"/v1/workloads/{name}/logs{query}")
+    except ApiError as exc:
+        print(f"{exc}", file=sys.stderr)
+        return 1
+
+    log = payload.get("log") or ""
+    if not log.strip():
+        # SILENCE AND A WRONG NAME LOOK IDENTICAL FROM THE SERVICE, so the name
+        # is checked HERE before silence is reported as normal.
+        #
+        # The route deliberately performs no lookup: a namespace composed from
+        # the caller's own token IS the ownership check, and reading the config
+        # repo to confirm a name would take `deployed()`'s lock and serialise
+        # every deploy behind an open browser tab. That reasoning is sound and
+        # is why this belongs in the client.
+        #
+        # A DEVELOPER LOST TIME TO EXACTLY THIS: they passed the POD name,
+        # `ag-fin-modules`, where the WORKLOAD name `fin-modules` was wanted,
+        # and got "Nothing in the last 60 minutes" — which reads as a quiet
+        # agent, not a bad argument. `DeploySpec.workloads()` is the one place
+        # the shape of the fleet is decided, and the CLI already has the spec.
+        if problem := _unknown_workload(name, project):
+            print(problem, file=sys.stderr)
+            return 2
+        # NOT AN ERROR, AND THIS IS THE COMMON CASE. A workload with no queue
+        # scales to zero and says nothing, so silence is the normal state rather
+        # than a failure to fetch — the service says which window it searched.
+        print(payload.get("note")
+              or f"Nothing in the last {minutes} minutes.")
+        return 0
+
+    lines = log.splitlines()
+    if tail and len(lines) > tail:
+        print(f"[showing the last {tail} of {len(lines)} lines]")
+        lines = lines[-tail:]
+    print("\n".join(lines))
+    return 0
+
+
+def _unknown_workload(name: str, project: str) -> str:
+    """A message naming the real workloads, or "" when nothing can be said.
+
+    SILENT WHEN THERE IS NO PROJECT TO READ. `elan logs` is legitimately run
+    from outside a checkout — against an environment somebody else deployed —
+    and refusing there would turn a working command into an error over a check
+    that is only ever a convenience.
+
+    AND SILENT WHEN THE CHECKOUT IS A DIFFERENT PROJECT, which is the trap this
+    walked into on its first run: `project.find()` searches UPWARD, so asking
+    about `--project other` from inside any checkout validated the name against
+    whatever `elan.yaml` happened to be above the working directory. The
+    platform's own suite caught it, because the repo has an `elan.yaml` of its
+    own and every existing test runs inside it.
+    """
+    from elan_cli import project as project_mod  # noqa: PLC0415
+
+    try:
+        spec = project_mod.find().spec
+    except Exception:
+        return ""
+    if spec.project != project:
+        return ""
+    known = spec.workloads()
+    if name in known:
+        return ""
+
+    lines = [f"No workload called {name!r} in this project."]
+    # THE POD PREFIX IS THE MISTAKE THAT HAPPENS, so it is named rather than
+    # left to the list below to imply.
+    if name.startswith("ag-") and name[3:] in known:
+        lines.append(f"\n  `ag-` is the POD's name in the cluster; the workload "
+                     f"is {name[3:]!r}.")
+    lines.append("\n  this project's workloads:")
+    for workload, members in sorted(known.items()):
+        lines.append(f"    {workload}  ({', '.join(sorted(members))})")
+    return "\n".join(lines)