elan-cli 0.1.0__py3-none-any.whl

elan_cli/scaffold.py

@@ -0,0 +1,408 @@
+"""`elan init` and `elan new` — the two files created together, always.
+
+THE WHOLE POINT IS THAT THEY CANNOT DRIFT. A target in the repo but not in
+`elan.yaml` is refused, and so is the reverse — in both directions, because an
+undeclared target is the one nobody reviewed and a declared one with no code
+would provision a database and a topic for nothing. A scaffolding command that
+wrote the module and left the developer to remember the YAML would be building
+exactly the failure the cross-check exists to catch.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from elan_agentkit_contracts import templates
+from elan_agentkit_contracts.identity import (
+    AGENT_SLUG_MAX_LEN,
+    AGENT_SLUG_MIN_LEN,
+    AGENT_SLUG_PATTERN,
+    PROJECT_SLUG_MAX_LEN,
+    PROJECT_SLUG_MIN_LEN,
+    TENANT_SLUG_MAX_LEN,
+    TENANT_SLUG_MIN_LEN,
+)
+
+from elan_cli.project import SPEC_FILENAME, ProjectError, add_target, find
+
+#: `agent` and `workflow` differ by the file the registry scans for, and by
+#: nothing else the scaffolder needs to know.
+KINDS = {"agent": ("agents", "agent.py"), "workflow": ("workflows", "workflow.py")}
+
+#: A SHA THAT IS OBVIOUSLY A PLACEHOLDER. `source.ref` must match a 40-character
+#: hex pattern, so it cannot be left blank — and a plausible-looking sha would
+#: be one somebody might not notice was invented. `elan deploy` resolves the
+#: branch and rewrites this before submitting.
+#:
+#: QUOTED IN THE RENDERED FILE, and that is not cosmetic: forty zeroes is a
+#: valid YAML INTEGER, so unquoted it reaches the schema as `0` and the error
+#: says "Input should be a valid string" about a field the developer can see
+#: plainly contains one. Any real sha starting with a digit and containing no
+#: letter would do the same.
+PLACEHOLDER_SHA = "0" * 40
+
+#: DELIBERATELY SHORT. A scaffolder that writes somebody's whole ignore file
+#: is guessing at their editor and their operating system; these three are the
+#: ones THIS TOOL causes.
+GITIGNORE = """\
+.env
+.venv/
+.elan/
+__pycache__/
+*.pyc
+"""
+
+#: THE NAMES ARE THE PLATFORM'S, NOT A LOCAL CONVENTION, which is the whole
+#: value of scaffolding this: a deployed pod reads `GOOGLE_API_KEY` because
+#: `llm.keys: {{google: ...}}` resolves to it through `providers.key_envs`. A
+#: developer who invented their own name here would have something that worked
+#: locally and read nothing in production.
+ENV_TEMPLATE = """\
+# Local development only, and git-ignored because it holds a key.
+#
+# A DEPLOYED POD NEVER READS THIS FILE. The platform injects the real values
+# from Secret Manager under these same names, which is why the names here are
+# worth matching exactly.
+
+# YOUR MODEL KEY, and the name is not yours to choose. `GOOGLE_` is a reserved
+# prefix — a tenant setting GOOGLE_CLOUD_PROJECT could point a cloud SDK
+# somewhere unintended — so you declare `llm.keys: {{google: <secret>}}` in
+# elan.yaml and the platform resolves it to this variable.
+GOOGLE_API_KEY=
+# ANTHROPIC_API_KEY=
+# OPENAI_API_KEY=
+
+# Lets MODEL_OVERRIDE work, and it is refused anywhere else. Overriding the
+# model substitutes what the manifest declared AFTER the deploy-time
+# `model in llm.models` check has already passed, so the allowlist would stop
+# describing what actually runs.
+AGENTKIT_ENV=local
+# MODEL_OVERRIDE=gemini-flash-latest
+
+# DELIBERATELY UNSET, and the runtime says so on every start rather than
+# failing: no ledger means runs are unbilled, and no actions service means
+# autonomy follows your manifest alone. Pointing these at the real services
+# from a laptop is not a local test, it is a remote one.
+# LEDGER_SERVICE_URL=
+# ACTIONS_SERVICE_URL=
+
+# DO NOT SET TARGET_SLUG HERE. It names which agent a pod runs, so with it set
+# every target would build as that one. `elan adk` strips it from what it
+# launches for exactly that reason, but anything else reading Settings obeys
+# it.
+"""
+
+README_TEMPLATE = """\
+# {project}
+
+Agents deployed to the Elan platform from this repository.
+
+## Getting set up
+
+Put your model key in `.env` (git-ignored), then:
+
+```bash
+elan env                                    # the runtime, into .venv
+elan validate                               # both files, checked against each other
+elan adk web                                # drive the agents locally
+```
+
+## The two files, and why there are two
+
+`elan.yaml` holds **deploy-time facts** — what to build, how big, what it may
+reach. Each agent's Python `MANIFEST` holds **runtime behaviour** — its model,
+its tools, what it may do without asking. No field appears in both. Where they
+look like they overlap they are in a validation relationship: the MANIFEST
+states what the agent asks for, `elan.yaml` states what the platform permits,
+and a deploy is refused on a mismatch.
+
+`elan new agent <slug>` writes both halves, which is the point of it.
+
+## Custom plugins
+
+A target may add ADK plugins of its own, declared in its `MANIFEST`:
+
+```python
+MANIFEST = AgentManifest(
+    ...,
+    plugins=[".plugins.Redactor"],   # plugins.py beside this file
+)
+```
+
+A leading dot is relative to the target's own package, like a Python import;
+without one it is absolute, for a plugin from a library in your
+`pyproject.toml`. The path names a `BasePlugin` subclass (constructed with no
+arguments) or an already-built instance — an instance is how a plugin gets
+configuration.
+
+**Keep it inside the target's directory.** The image is built from `agents/`
+and `workflows/` only, so a `lib/` at the repo root is there when your manifest
+is read and gone when the pod runs.
+
+Your plugins run **after** the platform's, and that ordering is fixed. ADK
+stops at the first callback that returns a value, so anything earlier would
+skip the platform's gates rather than sit beside them.
+
+Two ADK behaviours worth knowing before you write one: a nested `AgentTool` or
+`WorkflowTool` run fires **no** plugin callbacks at all, and `on_event_callback`
+does not fire for a run halted in `before_run_callback`.
+
+## Dependencies
+
+There is no `pyproject.toml` here and you may not need one. The platform's
+runtime image already carries ADK and the agentkit packages; add a
+`pyproject.toml` only for libraries **beyond** those, and the build will
+install it. Never put `agentkit-*` in it.
+
+## Deploying
+
+```bash
+git push          # elan deploy builds the REMOTE commit, not your disk
+elan deploy
+```
+"""
+
+
+def _slug_ok(slug: str, *, lo: int, hi: int) -> bool:
+    import re
+
+    return bool(lo <= len(slug) <= hi and re.match(AGENT_SLUG_PATTERN, slug))
+
+
+def _refuse_slug(slug: str, what: str, lo: int, hi: int) -> None:
+    raise ProjectError(
+        f"invalid {what} slug {slug!r}\n"
+        f"  must be {lo}-{hi} characters matching {AGENT_SLUG_PATTERN}\n"
+        f"  — starting with a letter, not ending in a hyphen, and with no\n"
+        f"  doubled hyphen. The cap is what keeps every derived DNS label\n"
+        f"  under 63 characters once a tenant and project are prefixed, and\n"
+        f"  the doubled-hyphen rule is what makes `--` unambiguous as the\n"
+        f"  separator between them."
+    )
+
+
+SPEC_TEMPLATE = '''\
+# What the platform provisions for this project.
+#
+# TWO FILES, AND NO FIELD IN BOTH. This one holds DEPLOY-TIME facts — what to
+# build, how big, what it may reach. Each target's Python MANIFEST holds RUNTIME
+# behaviour — its model, its tools, what it may do without asking. They are
+# checked against each other on every deploy, in both directions.
+apiVersion: elan.dev/v1
+kind: Project
+
+tenant: {tenant}
+project: {project}
+
+source:
+  repo: {repo}
+  # REWRITTEN BY `elan deploy`, which resolves your branch to a commit and puts
+  # the sha here before submitting — so a deployment is reproducible from this
+  # file alone. All zeroes until the first deploy.
+  ref: "{sha}"
+  # Must contain agents/<name>/agent.py and workflows/<name>/workflow.py.
+  targetsRoot: .
+  runtime: python3.12
+
+defaults:
+  # Every target inherits these and may override any of them. Autopilot bills a
+  # 250m / 512Mi floor whatever you ask for, so asking for less saves nothing.
+  resources: {{cpu: "500m", memory: "1Gi"}}
+  scaling: {{minReplicas: 0, maxReplicas: 3}}
+  llm:
+    # Every target's MANIFEST.model must be one of these. The list also decides
+    # which provider hosts your agents can reach at all — the egress allowlist
+    # is derived from it — so a model missing here fails as a refused
+    # connection naming the hostname.
+    models: [gemini-flash-latest]
+    # provider -> a name within YOUR OWN secrets, set with `elan secret set`.
+    # Not a Secret Manager id: the platform prefixes it with your tenant. The
+    # variable it arrives under is ours to choose (GOOGLE_API_KEY), because
+    # those names sit under reserved prefixes.
+    keys:
+      google: default
+  # THIRD PARTIES YOUR TOOLS CALL. Default-deny: anything not listed here is
+  # refused at the proxy by hostname. Your model providers are added
+  # automatically from `llm.models` above — you should not have to know which
+  # hostname a model lives on.
+  egress: []
+
+# Every agent and workflow in this repo, by slug. The set here must equal the
+# set the repo actually contains — in both directions, checked on every deploy.
+# `elan new` writes both halves so they cannot drift.
+targets:
+'''
+
+def init(directory: Path, *, tenant: str, project: str, repo: str,
+         agent: str = "hello-agent") -> int:
+    """Lay down `elan.yaml`, the directories the registry scans, and one agent.
+
+    IT CREATES AN AGENT BECAUSE AN EMPTY PROJECT DOES NOT PARSE. `DeploySpec`
+    refuses a spec with no targets — "a project with no agents deploys nothing"
+    — which is right for something about to be submitted, and it means there is
+    no such thing as a valid empty `elan.yaml`. Scaffolding one anyway would
+    hand the developer a file whose very first `elan validate` fails with a
+    schema error about a file they have not touched.
+
+    So `init` leaves a project that is complete rather than a project that is
+    started: one agent, declared, scaffolded, and passing validation.
+    """
+    if not _slug_ok(tenant, lo=TENANT_SLUG_MIN_LEN, hi=TENANT_SLUG_MAX_LEN):
+        _refuse_slug(tenant, "tenant", TENANT_SLUG_MIN_LEN, TENANT_SLUG_MAX_LEN)
+    if not _slug_ok(project, lo=PROJECT_SLUG_MIN_LEN, hi=PROJECT_SLUG_MAX_LEN):
+        _refuse_slug(project, "project", PROJECT_SLUG_MIN_LEN, PROJECT_SLUG_MAX_LEN)
+
+    spec_path = directory / SPEC_FILENAME
+    if spec_path.exists():
+        raise ProjectError(
+            f"{spec_path} already exists. `elan init` will not overwrite a "
+            "deploy file — it is the one thing in the repo that cannot be "
+            "regenerated from anything else."
+        )
+
+    directory.mkdir(parents=True, exist_ok=True)
+    (directory / "agents").mkdir(exist_ok=True)
+    (directory / "workflows").mkdir(exist_ok=True)
+    # WRITTEN HERE RATHER THAN LEFT TO THE DEVELOPER because `elan env` puts a
+    # virtualenv in this directory, and a committed one is both enormous and
+    # full of absolute paths from somebody else's machine. NOT OVERWRITTEN: a
+    # repo that already has one has it for reasons this does not know.
+    # NONE OF THESE OVERWRITE. A directory that already has one has it for
+    # reasons this does not know, and `init` refusing to clobber is the same
+    # rule elan.yaml gets a paragraph about above.
+    written = []
+    for name, body in (
+        (".gitignore", GITIGNORE),
+        (".env", ENV_TEMPLATE.format(project=project)),
+        ("README.md", README_TEMPLATE.format(project=project)),
+    ):
+        path = directory / name
+        if not path.exists():
+            path.write_text(body)
+            written.append(path)
+    spec_path.write_text(SPEC_TEMPLATE.format(
+        tenant=tenant, project=project, repo=repo, sha=PLACEHOLDER_SHA))
+    print(f"created {spec_path}")
+    print(f"        {directory / 'agents'}/")
+    print(f"        {directory / 'workflows'}/")
+    for path in written:
+        print(f"        {path}")
+
+    # WRITTEN DIRECTLY RATHER THAN THROUGH `new`, because `new` parses the spec
+    # to check the slug is free — and at this instant the spec does not parse.
+    _write_target("agent", agent, directory)
+    add_target(spec_path, agent)
+    print(f"        {directory / 'agents' / agent.replace('-', '_')}/agent.py")
+
+    _git_init(directory)
+
+    # THE ENVIRONMENT, ALWAYS, BECAUSE IT IS DERIVABLE NOW (ADR-0220).
+    #
+    # This block used to open "`init` CANNOT DERIVE THIS": the runtime lived in
+    # a checkout of the platform monorepo and nothing about a new repo says
+    # where that is, so it happened only when told — by `--runtime` or by
+    # `$ELAN_RUNTIME_SRC` — and was a printed instruction otherwise.
+    #
+    # PRINTING IT WAS NOT ENOUGH, which is the lesson worth keeping. "Next:
+    # elan env" under a heading reads as optional, and the next thing anybody
+    # does is `elan validate` or `adk web` — both of which then fail on the
+    # missing environment the line was about. That failure mode is now removed
+    # rather than mitigated, since there is nothing left to ask the developer
+    # for.
+    #
+    # THE INSTRUCTION SURVIVES FOR THE ONE CASE THAT CAN STILL HIT IT: no
+    # network, or no `uv`. Then the install fails, says why in uv's own words,
+    # and `Next:` leads with the command to retry.
+    from elan_cli import env as env_cmd  # noqa: PLC0415
+
+    print()
+    made_environment = env_cmd.run(directory) == 0
+
+    print()
+    print("Next:")
+    if not made_environment:
+        # STILL FIRST, because `validate` and `adk` both need it.
+        print("  elan env                      # installs the runtime into .venv")
+    print("  elan validate                 # checks both files against each other")
+    print("  elan adk web                  # drive it locally, plugins and all")
+    print("  elan new agent <slug>         # scaffolds a module AND declares it")
+    return 0
+
+
+def _git_init(directory: Path) -> None:
+    """Make this a git repository, if it is not one already.
+
+    NOT A CONVENIENCE. `elan deploy` resolves a branch to a commit and builds
+    THAT COMMIT FROM THE REMOTE — so an agent that is not in a repository
+    cannot be deployed at all, and the failure arrives much later, phrased as
+    a clone error. A scaffold that produces something undeployable is not
+    finished.
+
+    ALREADY-A-REPO INCLUDES A PARENT. `git rev-parse` walks up, so scaffolding
+    into a subdirectory of an existing repository correctly does nothing
+    rather than nesting one repo inside another — which git permits and then
+    behaves confusingly about.
+
+    SILENT WHEN GIT IS ABSENT. Nothing else here needs it, and refusing to
+    scaffold because a tool is missing would be the wrong trade.
+    """
+    import shutil  # noqa: PLC0415
+    import subprocess  # noqa: PLC0415
+
+    if not shutil.which("git"):
+        return
+    inside = subprocess.run(
+        ["git", "rev-parse", "--git-dir"], cwd=directory,
+        capture_output=True, text=True)
+    if inside.returncode == 0:
+        return
+    created = subprocess.run(
+        ["git", "init", "--quiet"], cwd=directory,
+        capture_output=True, text=True)
+    if created.returncode == 0:
+        print(f"        {directory / '.git'}/  (git init)")
+
+
+def _write_target(kind: str, slug: str, root: Path) -> Path:
+    """The module itself. Shared by `init` and `new` so they cannot diverge."""
+    package, filename = KINDS[kind]
+    module = slug.replace("-", "_")
+    directory = root / package / module
+    if directory.exists():
+        raise ProjectError(f"{directory} already exists")
+    directory.mkdir(parents=True)
+    path = directory / filename
+    path.write_text(templates.read(kind).format(
+        slug=slug, module=module, display_name=slug.replace("-", " ").title()))
+    return path
+
+
+def new(kind: str, slug: str, *, start: Path | None = None) -> int:
+    """Scaffold a target's module and declare it in the same command."""
+    if not _slug_ok(slug, lo=AGENT_SLUG_MIN_LEN, hi=AGENT_SLUG_MAX_LEN):
+        _refuse_slug(slug, kind, AGENT_SLUG_MIN_LEN, AGENT_SLUG_MAX_LEN)
+
+    project = find(start)
+
+    # ONE NAMESPACE ACROSS BOTH KINDS. An agent and a workflow sharing a slug
+    # would resolve to the same workload, database and topics — so the check is
+    # against every declared target, not against this kind's directory.
+    if slug in project.spec.targets:
+        raise ProjectError(
+            f"{slug!r} is already declared in {project.spec_path}."
+        )
+
+    # THE YAML SECOND, so a failure to write the module leaves the deploy file
+    # untouched rather than declaring a target that does not exist.
+    path = _write_target(kind, slug, project.targets_root)
+    add_target(project.spec_path, slug)
+
+    print(f"created {path}")
+    print(f"updated {project.spec_path}")
+    print()
+    print("Next:")
+    print(f"  1. Edit {path} — instruction, description, limits.")
+    print(f"  2. Set owner.team and owner.contacts for {slug} in "
+          f"{project.spec_path.name}.")
+    print("  3. elan validate")
+    return 0

elan_cli/secret.py

@@ -0,0 +1,105 @@
+"""`elan secret` — a tenant's own credentials, set and removed by the tenant.
+
+WHY THIS EXISTS AT ALL: rotating a provider key was a `gcloud` command run by
+platform staff. That makes the platform a bottleneck for the one operation a
+customer must be able to perform immediately — a leaked key is an emergency,
+and "raise a ticket" is the wrong answer to one.
+
+A VALUE GOES IN AND NEVER COMES OUT. There is no `get`, deliberately. A CLI
+that printed a secret would put it in a terminal, a scrollback and a screen
+share, and the pod that needs it reads Secret Manager directly. What can be
+listed is NAMES.
+
+THE VALUE IS NEVER AN ARGUMENT. `--value` would put the key in the shell
+history of everyone who uses it, so it is read from a file or from stdin —
+the same reason `gcloud secrets versions add` takes `--data-file`.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from elan_cli.client import Api
+
+#: The two subtrees a tenant owns. `llm` is a provider credential, resolved by
+#: provider name — `elan secret set llm google` sets what `llm.keys.google`
+#: in elan.yaml points at. `secrets` is whatever the tenant declared.
+KINDS = ("llm", "secrets")
+
+
+class SecretError(Exception):
+    """Phrased for the developer running the command."""
+
+
+def _read_value(from_file: str) -> str:
+    """From a file, or from stdin. NEVER from the command line.
+
+    STRIPPED OF ONE TRAILING NEWLINE and no more. Pressing Enter after pasting
+    a key adds one, and a provider answers a key with `\\n` on the end with a
+    401 that says the key is invalid — which sends somebody to regenerate a
+    perfectly good credential. Leading and internal whitespace is left alone:
+    some credentials legitimately contain it, and silently trimming those
+    would corrupt them.
+    """
+    if from_file == "-":
+        if sys.stdin.isatty():
+            print("reading the value from stdin; end with Ctrl-D",
+                  file=sys.stderr)
+        raw = sys.stdin.read()
+    else:
+        path = Path(from_file)
+        if not path.is_file():
+            raise SecretError(f"no such file: {from_file}")
+        raw = path.read_text()
+
+    value = raw[:-1] if raw.endswith("\n") else raw
+    if not value:
+        raise SecretError(
+            "the value is empty. A secret with no value is worse than none: "
+            "the pod starts and fails at its first call."
+        )
+    return value
+
+
+def set_(api: Api, kind: str, name: str, from_file: str) -> int:
+    if kind not in KINDS:
+        raise SecretError(f"kind must be one of {', '.join(KINDS)}")
+    api.request("POST", "/v1/secrets",
+                json={"kind": kind, "name": name, "value": _read_value(from_file)})
+    print(f"set {kind}/{name}")
+    # THE POD READS ITS ENVIRONMENT ONCE, AT STARTUP. External Secrets will
+    # refresh the projected Secret on its own schedule, and a pod already
+    # running keeps the value it started with — so a rotation is not live
+    # until something replaces the pod. Saying so beats a customer believing
+    # their compromised key is out of use.
+    print("  Running pods keep the value they started with. Redeploy, or wait")
+    print("  for them to scale to zero, before the new value is in use.")
+    return 0
+
+
+def ls(api: Api) -> int:
+    secrets = api.request("GET", "/v1/secrets").get("secrets", [])
+    if not secrets:
+        print("no secrets set")
+        return 0
+    width = max(len(f"{s['kind']}/{s['name']}") for s in secrets)
+    for entry in secrets:
+        path = f"{entry['kind']}/{entry['name']}"
+        print(f"{path:<{width}}  updated {entry['updated_at'][:10]}")
+    # SET OUT OF BAND IS INVISIBLE HERE, and a developer who put one there
+    # with gcloud would otherwise think it had not worked.
+    print()
+    print("Names only — values are never shown. A secret written directly to")
+    print("Secret Manager works and is not listed.")
+    return 0
+
+
+def rm(api: Api, kind: str, name: str) -> int:
+    if kind not in KINDS:
+        raise SecretError(f"kind must be one of {', '.join(KINDS)}")
+    api.request("DELETE", f"/v1/secrets/{kind}/{name}")
+    print(f"removed {kind}/{name}")
+    print("  Every version is gone. A pod already running is unaffected until")
+    print("  it restarts, and then it will not start at all.")
+    return 0

elan_cli/stream.py

@@ -0,0 +1,162 @@
+"""Watching a run happen, over rt-service's event socket.
+
+── WHY POLLING A TRANSCRIPT CANNOT WORK ─────────────────────────────────────
+
+`elan invoke` used to publish an invocation and then poll
+`GET /v1/sessions/<target>/<session>` until a reply appeared. It never did, for
+a reason no amount of waiting fixes: ADK writes a conversation to the AGENT'S
+OWN DATABASE (ADR-0036), and rt-service holds a connection to the PLATFORM's.
+So that route can read the platform canary's transcript and can never read a
+tenant's — it answers, correctly and forever, that there is nothing there.
+
+THE EVENT STREAM IS THE PATH THAT WAS DESIGNED FOR THIS. An agent publishes to
+`agent.events.<tenant>`, rt-service subscribes to a tenant lazily on its first
+socket and fans out to whoever is watching. Nothing in it touches a database.
+
+── THE ORDERING, WHICH IS THE WHOLE TRICK ───────────────────────────────────
+
+SUBSCRIBE FIRST, THEN INVOKE. Pub/Sub discards a message published to a topic
+with no subscription, and rt-service creates the tenant's subscription when the
+FIRST socket opens. So a client that invokes and then connects loses everything
+published in between — and on a warm agent that is the entire reply.
+
+rt-service's own websocket handler makes the same point in the other direction:
+it watches the tenant BEFORE sending `ready`, because a subscription created
+afterwards can miss the `started` for the message just sent.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import Any
+
+# ── MOVED TO `elan_sdk`, RE-EXPORTED HERE ────────────────────────────────────
+#
+# `text_of` is the only client code in this repo with a recorded bug and a
+# worked fix — reading the flat `payload["text"]` found nothing on every
+# content event and reported a run that had replied perfectly well as one that
+# "finished without saying anything" — so a second copy of it is exactly the
+# drift `ui/portal/lib/types.ts` already demonstrates. Same for the certifi
+# context, which is now in three places' worth of lessons and one module.
+#
+# RE-EXPORTED RATHER THAN REPLACED AT THE CALL SITES, because
+# `tests/test_elan_cli_invoke.py` imports `_trust` and `text_of` from here and
+# monkeypatches this module's socket — and those tests passing UNCHANGED is
+# what proves the extraction moved nothing.
+from elan_sdk._tls import trust as _trust  # noqa: F401
+from elan_sdk.models.events import SHOWN_KINDS as SHOWN  # noqa: F401
+from elan_sdk.models.events import TERMINAL_KINDS as TERMINAL  # noqa: F401
+from elan_sdk.models.events import author_of, ends_the_run, text_of  # noqa: F401
+from elan_sdk.stream import CONTROL
+
+
+class StreamError(Exception):
+    """The socket could not be opened or authenticated."""
+
+
+@contextmanager
+def watching(api: str, token: str, session_id: str,
+             open_socket=None) -> Iterator[Any]:
+    """Hold an authenticated, subscribed socket open.
+
+    A CONTEXT MANAGER BECAUSE THE ORDER IS THE POINT: the caller invokes INSIDE
+    the `with`, which is what guarantees the subscription exists before the
+    agent can publish anything.
+    """
+    from elan_agentkit_contracts.tickets import stream_url  # noqa: PLC0415
+
+    base = api.replace("https://", "wss://").replace("http://", "ws://") + "/ws"
+    opener = open_socket or _connect
+    # THE CREDENTIAL IS ON THE HANDSHAKE (ADR-0163), and `stream_url` is the
+    # ONE composer in Python — shared with the SDK.
+    #
+    # THE TRANSPORTS STAY SEPARATE AND THE PREDICATE DOES NOT. This module is
+    # `websockets.sync` and the SDK's is `websockets.asyncio`, which cannot be
+    # one implementation; where the credential goes is not transport, and a
+    # second copy of it here is exactly the duplication ADR-0116 measured —
+    # last time it cost this file a hang on every paused run.
+    socket = opener(stream_url(base, token))
+    try:
+        opening = json.loads(socket.recv())
+        if opening.get("type") != "ready":
+            raise StreamError(
+                f"the event stream refused this token: {opening!r}")
+
+        socket.send(json.dumps({"type": "subscribe", "session_id": session_id}))
+        # WAITED FOR, NOT ASSUMED. `subscribed` is the acknowledgement that
+        # this connection is registered for the session; invoking before it
+        # arrives reopens the race the whole ordering exists to close.
+        while True:
+            message = json.loads(socket.recv())
+            if message.get("type") == "subscribed":
+                break
+            if message.get("type") == "error":
+                raise StreamError(str(message))
+        yield socket
+    finally:
+        try:
+            socket.close()
+        except Exception:
+            # A socket we could not close cleanly is closed by the server when
+            # the process exits. Failing the command over it would be worse.
+            pass
+
+
+def replies(socket, invocation_id: str) -> Iterator[dict]:
+    """Events for ONE invocation, until it ends.
+
+    FILTERED BY INVOCATION because a session can carry several. A socket
+    subscribed to the session sees them all, and printing another run's output
+    as this one's is worse than printing nothing.
+
+    THE TWO PREDICATES ARE THE SDK'S AND NOT THIS MODULE'S (ADR-0116), which
+    is the whole reason this loop is four lines of filtering and no judgement.
+    It owned both once and both had drifted:
+
+      * it stopped at `kind in TERMINAL`, so A PAUSED RUN NEVER ENDED. A run
+        suspended for a human emits two `paused` events and no `finished` at
+        all — the pause IS where it stopped — so this blocked in `recv()` for
+        ever on a workflow that was sitting there asking a question, and
+        `websockets.sync`'s `recv()` has no default timeout to save it.
+        `ends_the_run` knows the engine's terminal pause; `TERMINAL` could
+        not.
+      * its control set was `{pong, subscribed, ready}` against the SDK's
+        `{pong, subscribed, ready, error}`. Harmless only by accident — an
+        error frame carries no `invocation_id`, so the next line dropped it.
+
+    A rule each client spells for itself is a rule that drifts, because each
+    client's own tests pass against its own copy and nothing compares them.
+    """
+    while True:
+        raw = socket.recv()
+        try:
+            event = json.loads(raw)
+        except ValueError:
+            continue
+        if not isinstance(event, dict):
+            continue
+        if event.get("type") in CONTROL:
+            continue
+        if event.get("invocation_id") != invocation_id:
+            continue
+        yield event
+        if ends_the_run(event):
+            return
+
+
+def _connect(url: str):
+    try:
+        from websockets.sync.client import connect  # noqa: PLC0415
+    except ImportError as exc:  # pragma: no cover - a packaging fault
+        raise StreamError(
+            "this CLI was installed without websocket support, so it cannot "
+            "watch a run. Reinstall it."
+        ) from exc
+
+    # ONLY FOR `wss://`. Passing a context to a plain ws:// connection is an
+    # error rather than a no-op, and local development uses ws://.
+    context = _trust() if url.startswith("wss://") else None
+    return connect(url, ssl=context, open_timeout=30,
+                   max_size=4 * 1024 * 1024)