lighthouse-cli 0.16.0__py3-none-any.whl

lighthouse/commands/connections.py

@@ -0,0 +1,201 @@
+# Copyright 2026 Atlantic Agentic Labs. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""`lighthouse connections`: what is connected, how often each syncs, and Sync now.
+
+    lighthouse connections                         # every connection, its schedule, next sync
+    lighthouse connections schedule cx-abcdef123456 --mode hourly
+    lighthouse connections schedule cx-abcdef123456 --mode daily --at 06:30 --tz Europe/London
+    lighthouse connections schedule cx-abcdef123456 --mode off
+    lighthouse connections sync cx-abcdef123456 --reason "a page was fixed this morning"
+
+**The listing** reads `GET /api/v1/connectors`, the same connections the
+Connect page shows, with each one's schedule as the deployment reports it
+(contract 1.17): the mode in words, the last and next sync, and a change that
+was asked for but not yet confirmed, shown as asked for rather than taken for
+what runs.
+
+**`schedule` and `sync` act**, so they are the person, not the CLI's token:
+`PUT /api/v1/connections/<id>/schedule` and `POST /api/v1/connections/<id>/sync`
+with the person's own Cloudflare Access session for the tenant host, from
+`cloudflared access token`, exactly as `connect --credential-stdin` does it.
+A delegated token administers nothing (`docs/adr/0012-delegated-credentials.md`),
+and the service refuses a machine key and AAL staff here as it does on the
+card. Each is a signed `connector.schedule` or `connector.sync` command to the
+deployment, audited against the person.
+
+**The rules are the service's.** `--mode`, `--at` and `--tz` are sent as
+given and checked by the same function that checks the card
+(`commands.schedule_params`): off, every_15m, hourly, working_hours (with
+`--tz`) or daily (with `--at` HH:MM and `--tz`). A refusal names the field
+and exits 2. Asking for the schedule already asked for sends nothing and says
+so; so does Sync now while one is still in hand.
+"""
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+from lighthouse.commands import connect as _connect
+from lighthouse.exits import USAGE, CliError
+from lighthouse.flags import inherited
+from lighthouse.http import Refused
+from lighthouse.main import Command, Context
+from lighthouse.out import Out
+
+
+def _configure(ap: argparse.ArgumentParser) -> None:
+    sub = ap.add_subparsers(dest="connections_command", metavar="<subcommand>")
+    sub.add_parser("list", parents=[inherited()],
+                   help="every connection, its sync schedule and next sync (the default)")
+    sched = sub.add_parser("schedule", parents=[inherited()],
+                           help="set how often a connection syncs (client_admin, as yourself)")
+    sched.add_argument("connection", help="the connection's id, cx-...")
+    sched.add_argument("--mode", required=True,
+                       help="off, every_15m, hourly, working_hours or daily")
+    sched.add_argument("--at", default=None, help="with --mode daily: the time, 24-hour HH:MM")
+    sched.add_argument("--tz", default=None,
+                       help="with working_hours or daily: a time zone, e.g. Europe/London")
+    _source_args(sched)
+    sync = sub.add_parser("sync", parents=[inherited()],
+                          help="sync a connection now (client_admin, as yourself)")
+    sync.add_argument("connection", help="the connection's id, cx-...")
+    _source_args(sync)
+
+
+def _source_args(ap: argparse.ArgumentParser) -> None:
+    ap.add_argument("--card", default=None,
+                    help="the source, <pack>:<card>, where the deployment reports more than one")
+    ap.add_argument("--deployment", default=None,
+                    help="the deployment, where the source runs in more than one")
+    ap.add_argument("--reason", default=None, help="why, for the audit log")
+
+
+def _row(c: dict[str, Any]) -> dict[str, Any]:
+    sched = c.get("schedule") or {}
+    requested = sched.get("requested") or {}
+    return {"id": c.get("id"), "connector": c.get("connector"), "label": c.get("label"),
+            "state": c.get("state"), "schedule": sched.get("words") or sched.get("mode"),
+            "mode": sched.get("mode"), "pending": bool(sched.get("pending")),
+            "requested": requested.get("words") if sched.get("pending") else None,
+            "syncing": bool(sched.get("syncing")),
+            "last_sync_at": c.get("last_sync_at"), "next_sync_at": c.get("next_sync_at"),
+            # 1.27: the deployment's last check, and what to do about it.
+            **check_of(c)}
+
+
+# The deployment's check codes that need the client to act (contract 1.18,
+# and 1.27's two for the finance wave), in plain words. The service's own
+# `health.fix` says what to do where it gives one.
+CHECK_WORDS = {
+    "write_capable": "the key can move money: refused, nothing is read",
+    "unverified": "the provider does not state the key's permissions: confirm it is view-only",
+    "scope_missing": "it signs in but lacks a scope, or grants one that writes",
+    "auth_failed": "the provider refused it",
+    "absent": "nothing is stored under it",
+}
+
+
+def check_of(c: dict[str, Any]) -> dict[str, Any]:
+    """The last check's code, its words, and the fix, for a failing card."""
+    health = c.get("health") or {}
+    code = str(health.get("code") or "")
+    if c.get("state") != "failing" or code not in CHECK_WORDS:
+        return {"check": None, "check_words": None, "fix": None}
+    return {"check": code, "fix": str(health.get("fix") or "") or None,
+            "check_words": CHECK_WORDS[code]}
+
+
+def _list(ctx: Context) -> dict[str, Any]:
+    body = ctx.client().get("/api/v1/connectors") or {}
+    rows = [_row(c) for c in body.get("connections") or [] if c.get("state") != "disconnected"]
+    return {"ok": True, "connections": rows,
+            "schedule_modes": [m.get("mode") for m in body.get("schedule_modes") or []]}
+
+
+def _act(ctx: Context, method: str, suffix: str, body: dict[str, Any]) -> dict[str, Any]:
+    """The request, as the person, with the service's refusal said in the
+    command line's terms."""
+    cid = str(ctx.args.connection)
+    host = ctx.host
+    client = ctx.new_client(host, None, session=_connect.person_session(host))
+    try:
+        got = client.request(method, f"/api/v1/connections/{cid}/{suffix}",
+                             json_body={k: v for k, v in body.items() if v is not None}) or {}
+    except Refused as e:
+        if e.error == "invalid":
+            raise CliError(e.message, code=USAGE, error="invalid",
+                           hint="see `lighthouse connections schedule --help`") from None
+        if e.error == "commands_disabled":
+            raise CliError(e.message, code=e.code, error=e.error,
+                           hint=f"a client administrator switches connector.schedule and "
+                                f"connector.sync on at https://{host}/command-settings") from None
+        raise
+    finally:
+        client.close()
+    command = got.get("command") or {}
+    return {"ok": True, "connection": got.get("id") or cid, "connector": got.get("connector"),
+            "label": got.get("label"), "unchanged": bool(got.get("unchanged")),
+            "command": command.get("command_id"), "command_status": command.get("status"),
+            **{k: v for k, v in _row(got).items()
+               if k not in ("id", "connector", "label", "state", "check", "check_words", "fix")}}
+
+
+def _schedule(ctx: Context) -> dict[str, Any]:
+    a = ctx.args
+    out = _act(ctx, "PUT", "schedule", {"mode": a.mode, "at": a.at, "tz": a.tz, "card": a.card,
+                                        "deployment": a.deployment, "reason": a.reason})
+    return {**out, "action": "schedule"}
+
+
+def _sync(ctx: Context) -> dict[str, Any]:
+    a = ctx.args
+    out = _act(ctx, "POST", "sync", {"card": a.card, "deployment": a.deployment,
+                                     "reason": a.reason})
+    return {**out, "action": "sync"}
+
+
+def connections(ctx: Context) -> dict[str, Any]:
+    which = getattr(ctx.args, "connections_command", None) or "list"
+    if which == "schedule":
+        return _schedule(ctx)
+    if which == "sync":
+        return _sync(ctx)
+    return _list(ctx)
+
+
+def _when(value: Any) -> str:
+    return str(value) if value else "-"
+
+
+def _show(out: Out, body: dict[str, Any]) -> None:
+    if "action" not in body:
+        out.table(["connection", "connector", "what", "state", "schedule", "last sync",
+                   "next sync"],
+                  [[c["id"], c["connector"], c["label"], c["state"],
+                    c["schedule"] + (f" (asked: {c['requested']})" if c["requested"] else "")
+                    + (" · syncing" if c["syncing"] else ""),
+                    _when(c["last_sync_at"]), _when(c["next_sync_at"])]
+                   for c in body["connections"]])
+        for c in body["connections"]:
+            if c.get("check"):
+                out.note(f"{c['id']} ({c['connector']}) is failing: {c['check_words']} "
+                         f"({c['check']}).{' ' + c['fix'] if c.get('fix') else ''}")
+        out.note("`lighthouse connections schedule <id> --mode ...` sets one; "
+                 "`lighthouse connections sync <id>` syncs one now")
+        return
+    if body["action"] == "schedule":
+        out.pairs([("connection", body["connection"]), ("schedule", body["schedule"]),
+                   ("asked for", body["requested"] or body["schedule"]),
+                   ("next sync", _when(body["next_sync_at"])),
+                   ("command", body["command"] or "")])
+        out.note("already asked for: nothing new was sent" if body["unchanged"] else
+                 "sent to your deployment; the card shows it once the deployment confirms")
+        return
+    out.pairs([("connection", body["connection"]), ("syncing", "yes"),
+               ("last sync", _when(body["last_sync_at"])), ("command", body["command"] or "")])
+    out.note("a sync is already in hand: nothing new was sent" if body["unchanged"] else
+             "sent to your deployment; it syncs at its scheduler's next tick")
+
+
+COMMANDS = (Command("connections", "your connections' sync schedules, set one, or sync now",
+                    _configure, connections, _show),)

lighthouse/commands/evals.py

@@ -0,0 +1,198 @@
+"""`lighthouse evals`: evaluation results, and running a set.
+
+    lighthouse evals                          # the latest results
+    lighthouse evals list --pack research --json
+    lighthouse evals list --fail-below 0.8    # a release gate on metrics.f1
+    lighthouse evals run research:summary --cap 5 --wait --fail-below 0.8
+
+`evals` reads `GET /api/v1/evals`, every page of it: each row is one measurement
+of one suite for one agent version, with `passed` (did it meet its own bar) and
+`metrics`, a set of named numbers that depends on the suite.
+
+**There is no single `score` on a row.** A suite reports whatever measures it
+(`f1` is the one the API documents). So `--fail-below N` gates on one named
+metric, `--metric` (default `f1`), and **fails closed**: a row with no number
+under that name cannot be shown to meet the bar, so the command exits 1 and says
+which rows. A release gate that passed on what it could not read would be worse
+than none.
+
+**`evals run` asks your deployment to run the agent's scheduled evaluation
+once** (contract 1.19, `POST /api/v1/agents/{agent}/evals`), under the spend
+cap you give (`--cap`, required: nothing runs without one), optionally only
+one eval set (`--set`, the eval card's id). It needs `eval.run` switched on
+by your organisation and by your deployment's own policy, and a person's
+token with the `deploy` scope (a machine key cannot spend). The deployment's
+scheduler runs it at its next tick, every 15 minutes by default.
+
+`--wait` follows it: the command until your deployment accepts it, then the
+evaluation rows it produces for that agent. The run **fails** (exit 1) when a
+new row did not pass, and, with `--fail-below N`, when a new row's metric is
+below N or missing (the same closed gate as `evals list --fail-below`). In a
+pipeline:
+
+    lighthouse evals run research:summary --cap 5 --wait --fail-below 0.8 \
+        && lighthouse agents deploy research:summary --version "$VERSION" --wait
+"""
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+from lighthouse.exits import FAILED, USAGE, CliError
+from lighthouse.flags import inherited
+from lighthouse.main import Command, Context
+from lighthouse.out import Out
+
+DEFAULT_METRIC = "f1"
+
+
+def _configure(ap: argparse.ArgumentParser) -> None:
+    sub = ap.add_subparsers(dest="evals_command", metavar="<subcommand>")
+    listing = sub.add_parser("list", parents=[inherited()], help="the latest results (the default)")
+    listing.add_argument("--pack")
+    listing.add_argument("--family")
+    listing.add_argument("--fail-below", type=float, dest="fail_below",
+                         help="exit 1 if any row's metric is below this, or has no such metric")
+    listing.add_argument("--metric", default=DEFAULT_METRIC,
+                         help="the metric --fail-below reads from each row's `metrics` "
+                              f"(default: {DEFAULT_METRIC})")
+    run = sub.add_parser("run", parents=[inherited()],
+                         help="run an agent's evaluation once, under a spend cap")
+    run.add_argument("agent", help="pack:card, e.g. research:summary")
+    run.add_argument("--cap", type=float, required=True, dest="cap",
+                     help="the most this run may spend, in US dollars")
+    run.add_argument("--set", dest="eval_set", help="one eval set (its eval card's id)")
+    run.add_argument("--deployment", help="the deployment, where the tenant has more than one")
+    run.add_argument("--reason", default=None, help="why, for the audit log")
+    run.add_argument("--wait", action="store_true",
+                     help="wait for the evaluation's results, and gate on them")
+    run.add_argument("--wait-timeout", type=float, default=1800.0, dest="wait_timeout",
+                     help="seconds to wait at most (default 1800); then exit 5")
+    run.add_argument("--fail-below", type=float, dest="fail_below",
+                     help="with --wait: exit 1 if a new row's metric is below this, or missing")
+    run.add_argument("--metric", default=DEFAULT_METRIC,
+                     help=f"the metric --fail-below reads (default: {DEFAULT_METRIC})")
+
+
+def evals(ctx: Context) -> dict[str, Any]:
+    if getattr(ctx.args, "evals_command", None) == "run":
+        return _run(ctx)
+    body = ctx.client().get_all("/api/v1/evals", "evals", pack=getattr(ctx.args, "pack", None),
+                                family=getattr(ctx.args, "family", None))
+    floor = getattr(ctx.args, "fail_below", None)
+    if floor is None:
+        return {"ok": True, **body}
+    return gate(body, floor, getattr(ctx.args, "metric", None) or DEFAULT_METRIC)
+
+
+def _run(ctx: Context) -> dict[str, Any]:
+    from lighthouse.commands.agents import wait_for
+    a = ctx.args
+    agent = str(a.agent)
+    pack, sep, card = agent.partition(":")
+    if not sep or not pack or not card:
+        raise CliError("the agent is pack:card, e.g. research:summary", code=USAGE,
+                       error="usage")
+    if a.cap <= 0:
+        raise CliError("--cap is above zero: nothing runs without a spend cap", code=USAGE,
+                       error="usage")
+    if a.fail_below is not None and not a.wait:
+        raise CliError("--fail-below gates on the results, so it needs --wait", code=USAGE,
+                       error="usage")
+    body: dict[str, Any] = {"cap_usd": f"{a.cap:.2f}",
+                            "reason": a.reason or "evaluation run from the lighthouse CLI"}
+    if a.eval_set:
+        body["set"] = a.eval_set
+    if a.deployment:
+        body["deployment"] = a.deployment
+    client = ctx.client()
+    cmd = client.post(f"/api/v1/agents/{agent}/evals", body)
+    out: dict[str, Any] = {"ok": True, "action": "run", "agent": agent,
+                           "command": cmd.get("command_id"), "status": cmd.get("status"),
+                           "cap_usd": (cmd.get("params") or {}).get("cap_usd", body["cap_usd"])}
+    if not a.wait:
+        return out
+    cid = cmd["command_id"]
+    got = wait_for(ctx, lambda: client.get(f"/api/v1/agents/{agent}/commands/{cid}"),
+                   lambda d: d.get("status") in ("applied", "refused", "failed", "expired"),
+                   "your deployment to accept the evaluation")
+    if got.get("status") != "applied":
+        raise CliError(f"your deployment did not take the evaluation: {got.get('status')}"
+                       + (f" ({got.get('reason')})" if got.get("reason") else ""),
+                       code=FAILED, error=f"command_{got.get('status')}", command=cid,
+                       reason=got.get("reason"))
+    since = _when(got.get("updated_at") or cmd.get("issued_at"))
+
+    def fresh() -> list[dict[str, Any]]:
+        rows = client.get_all("/api/v1/evals", "evals", pack=pack).get("evals") or []
+        return [r for r in rows if str(r.get("agent")).split(":")[-1] == card
+                and since is not None and (_when(r.get("ts")) or since) >= since]
+    rows = wait_for(ctx, lambda: {"rows": fresh()}, lambda d: bool(d["rows"]),
+                    "the evaluation's results (it runs at the scheduler's next tick)")["rows"]
+    out.update({"status": "measured", "evals": rows})
+    failed = [_name(r) for r in rows if r.get("passed") is False]
+    if a.fail_below is not None:
+        gate({"evals": rows}, a.fail_below, a.metric or DEFAULT_METRIC)
+    if failed:
+        raise CliError(f"{len(failed)} evaluation row(s) did not pass", code=FAILED,
+                       error="evaluation_failed", failed=failed)
+    return out
+
+
+def gate(body: dict[str, Any], floor: float, metric: str) -> dict[str, Any]:
+    """`--fail-below`: every row's `metric` at or above `floor`, failing
+    closed on a row that has none (B6)."""
+    rows = body.get("evals") or []
+    if not rows:
+        raise CliError(f"cannot apply --fail-below {floor}: there are no evaluation results to "
+                       f"read, and a gate with nothing to check fails closed",
+                       code=FAILED, error="no_results")
+    unreadable = [r for r in rows if not _number((r.get("metrics") or {}).get(metric))]
+    below = [r for r in rows if r not in unreadable
+             and float(r["metrics"][metric]) < floor]
+    if unreadable:
+        raise CliError(
+            f"cannot apply --fail-below {floor}: {len(unreadable)} of {len(rows)} evaluation "
+            f"row(s) have no numeric `{metric}` in their metrics. The API gives a row "
+            f"`passed` and a suite-specific `metrics` object, not one score, so the gate "
+            f"fails closed", code=FAILED, error="no_score",
+            hint="pass --metric <name> for a metric these suites report, or filter with "
+                 "--pack/--family",
+            unreadable=[_name(r) for r in unreadable])
+    if below:
+        raise CliError(f"{len(below)} evaluation row(s) have {metric} below {floor}",
+                       code=FAILED, error="below_threshold", below=[_name(r) for r in below])
+    return {"ok": True, **body, "below": []}
+
+
+def _when(value: Any) -> Any:
+    from datetime import datetime
+    try:
+        return datetime.fromisoformat(str(value).replace("Z", "+00:00"))
+    except ValueError:
+        return None
+
+
+def _number(value: Any) -> bool:
+    return isinstance(value, (int, float)) and not isinstance(value, bool)
+
+
+def _name(row: dict[str, Any]) -> str:
+    return ":".join(str(row.get(k)) for k in ("agent", "family", "suite") if row.get(k))
+
+
+def _show(out: Out, body: dict[str, Any]) -> None:
+    if body.get("action") == "run" and "evals" not in body:
+        out.pairs([("agent", body["agent"]), ("cap", f"${body['cap_usd']}"),
+                   ("command", body.get("command") or ""), ("status", body.get("status") or "")])
+        out.note("your deployment runs it at its scheduler's next tick; `--wait` follows it")
+        return
+    out.table(["agent", "pack", "family", "suite", "version", "passed", "metrics", "measured"],
+              [[r.get("agent"), r.get("pack"), r.get("family"), r.get("suite"), r.get("version"),
+                "yes" if r.get("passed") else "no",
+                ", ".join(f"{k}={v}" for k, v in sorted((r.get("metrics") or {}).items())),
+                r.get("ts")] for r in body["evals"]])
+
+
+COMMANDS = (Command("evals", "evaluation results, and running a set",
+                    _configure, evals, _show),)

lighthouse/commands/kb.py

@@ -0,0 +1,224 @@
+# Copyright 2026 Atlantic Agentic Labs. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""`lighthouse kb`: knowledge bases, their freshness, and ingesting into them.
+
+    lighthouse kb                      # every knowledge base, with its freshness
+    lighthouse kb show <index>
+    lighthouse kb ingest ops --source confluence --wait
+    lighthouse kb ingest ops --source cx-abcdef123456
+    lighthouse kb upload <file> [--deployment NAME]                  (contract 1.21)
+
+`kb` and `kb show` read `GET /api/v1/knowledge-bases` and
+`/api/v1/knowledge-bases/{index}` (contract 1.14): the indexes, what is in
+them, when each was last refreshed and where it is held — which, for every
+client, is the client's own account. Nothing is copied to AAL
+(https://docs.atlanticagenticlabs.com/).
+
+**`kb ingest` is `connections sync` by another name**, kept because the docs
+and people's scripts use it. `--source` is a connection id (`cx-...`) or a
+connector (`confluence`, `github`...); a connector with more than one live
+connection is narrowed by `--repo` (matched against the connection's label
+and target) or refused with the ids to choose from. It then sends
+`POST /api/v1/connections/<id>/sync` as you, with your own Cloudflare Access
+session (`cloudflared access login https://<host>`), exactly as
+`connections sync` does, to the knowledge base's own deployment.
+
+`--wait` polls the connection's schedule record, which the deployment
+reports, until a sync newer than the request has finished: exit 0 when it
+reports `ok`, exit 1 when it reports `failed`, exit 5 at `--wait-timeout`.
+
+`kb upload` sends a file to the deployment's own uploads store without it
+passing through LightHouse: it asks `POST /api/v1/uploads` for a link (the
+deployment mints it, `upload.prepare`), waits for the link, and PUTs the file
+straight to it. The deployment's uploads source indexes it at its next sync.
+"""
+from __future__ import annotations
+
+import argparse
+from typing import Any
+
+from lighthouse.commands import connect as _connect
+from lighthouse.exits import FAILED, USAGE, CliError
+from lighthouse.flags import inherited
+from lighthouse.main import Command, Context
+from lighthouse.out import Out
+
+
+
+def _configure(ap: argparse.ArgumentParser) -> None:
+    sub = ap.add_subparsers(dest="kb_command", metavar="<subcommand>")
+    sub.add_parser("list", parents=[inherited()], help="every knowledge base (the default)")
+    show = sub.add_parser("show", parents=[inherited()], help="one knowledge base")
+    show.add_argument("index", help="the index's name")
+    ingest = sub.add_parser("ingest", parents=[inherited()],
+                            help="sync a connection into a knowledge base now (as yourself)")
+    ingest.add_argument("index")
+    ingest.add_argument("--source", required=True,
+                        help="a connection id (cx-...) or a connector: github, gitlab, "
+                             "confluence, jira, gdrive…")
+    ingest.add_argument("--repo", help="narrow a connector to one connection by its label or "
+                                       "target, e.g. owner/name")
+    ingest.add_argument("--path", help=argparse.SUPPRESS)
+    ingest.add_argument("--reason", default=None, help="why, for the audit log")
+    ingest.add_argument("--wait", action="store_true", help="wait for the sync to finish")
+    ingest.add_argument("--wait-timeout", type=float, default=1800.0, dest="wait_timeout",
+                        help="seconds to wait at most (default 1800); then exit 5")
+    upload = sub.add_parser("upload", parents=[inherited()],
+                            help="upload a file straight to your deployment's own store")
+    upload.add_argument("file", help="the file: .md, .txt, .csv, .pdf, .docx, .pptx, .xlsx…")
+    upload.add_argument("--deployment", help="which deployment, where you have more than one")
+
+
+LINK_WAIT_S = 120
+
+
+def _upload(ctx: Context) -> dict[str, Any]:
+    """Ask for a link, wait for the deployment to mint it, PUT the file to it.
+    The file's bytes go only to the link: never to LightHouse."""
+    import time
+    from pathlib import Path
+
+    import httpx
+    path = Path(ctx.args.file)
+    if not path.is_file():
+        raise CliError(f"{path} is not a file", code=USAGE, error="usage")
+    data = path.read_bytes()
+    client = ctx.client()
+    body: dict[str, Any] = {"filename": path.name, "size": len(data)}
+    if ctx.args.deployment:
+        body["deployment"] = ctx.args.deployment
+    up = client.post("/api/v1/uploads", body)
+    sleep = ctx.sleep or time.sleep
+    for _ in range(LINK_WAIT_S):
+        if up.get("link") or up.get("status") in ("refused", "failed", "expired"):
+            break
+        sleep(1)
+        up = client.get(f"/api/v1/uploads/{up['upload_id']}")
+    link = up.get("link")
+    if not link:
+        raise CliError(f"no upload link: {up.get('about') or up.get('status')}",
+                       error=str(up.get("reason") or up.get("status") or "no_link"),
+                       hint="switch upload.prepare on in LightHouse's command settings and in "
+                            "your deployment's own policy")
+    try:
+        with httpx.Client(timeout=300.0, transport=ctx.transport,
+                          follow_redirects=False) as raw:
+            got = raw.request(link["method"], link["url"], content=data,
+                              headers=dict(link.get("headers") or {}))
+    except httpx.HTTPError as e:
+        raise CliError(f"the upload to your store did not complete: {type(e).__name__}",
+                       error="upload_failed") from None
+    if not 200 <= got.status_code < 300:
+        raise CliError(f"your store refused the upload (HTTP {got.status_code})",
+                       error="upload_refused")
+    return {"ok": True, "upload_id": up["upload_id"], "key": up.get("key"),
+            "deployment": up.get("deployment"), "bytes": len(data),
+            "indexed": "at your deployment's next sync of its uploads source"}
+
+
+def kb(ctx: Context) -> dict[str, Any]:
+    which = getattr(ctx.args, "kb_command", None) or "list"
+    if which == "upload":
+        return _upload(ctx)
+    if which == "ingest":
+        return _ingest(ctx)
+    if which == "show":
+        index = ctx.args.index
+        if not index:
+            raise CliError("which knowledge base?", code=USAGE, error="usage")
+        return {"ok": True, **ctx.client().get(f"/api/v1/knowledge-bases/{index}")}
+    return {"ok": True, **ctx.client().get("/api/v1/knowledge-bases")}
+
+
+def _resolve(ctx: Context, connections: list[dict[str, Any]]) -> dict[str, Any]:
+    a = ctx.args
+    live = [c for c in connections if c.get("state") != "disconnected"]
+    hit = [c for c in live if c.get("id") == a.source]
+    if not hit:
+        hit = [c for c in live if c.get("connector") == str(a.source).lower()]
+        if a.repo:
+            want = str(a.repo).lower()
+            hit = [c for c in hit if want in str(c.get("label") or "").lower()
+                   or want in " ".join(str(v) for v in (c.get("target") or {}).values()).lower()]
+    if not hit:
+        raise CliError(f"no live connection matches {a.source!r}"
+                       + (f" and {a.repo!r}" if a.repo else ""), code=USAGE,
+                       error="no_connection", hint="`lighthouse connections` lists them")
+    if len(hit) > 1:
+        raise CliError(f"{len(hit)} connections match {a.source!r}: name one", code=USAGE,
+                       error="ambiguous_connection",
+                       hint="pass its id as --source, or --repo; one of: "
+                            + ", ".join(sorted(str(c.get("id")) for c in hit)))
+    return hit[0]
+
+
+def _ingest(ctx: Context) -> dict[str, Any]:
+    from lighthouse.commands.agents import wait_for
+    from lighthouse.commands.connections import _row
+    a = ctx.args
+    base = ctx.client().get(f"/api/v1/knowledge-bases/{a.index}")
+    conn = _resolve(ctx, ctx.client().get("/api/v1/connectors").get("connections") or [])
+    cid = str(conn["id"])
+    before = (conn.get("schedule") or {}).get("last_sync_at")
+    host = ctx.host
+    person = ctx.new_client(host, None, session=_connect.person_session(host))
+    try:
+        got = person.post(f"/api/v1/connections/{cid}/sync", {k: v for k, v in {
+            "deployment": base.get("deployment"),
+            "reason": a.reason or f"ingest into {a.index} from the lighthouse CLI"}.items()
+            if v is not None}) or {}
+    finally:
+        person.close()
+    out: dict[str, Any] = {"ok": True, "action": "ingest", "index": a.index,
+                           "connection": cid, "connector": conn.get("connector"),
+                           "unchanged": bool(got.get("unchanged")),
+                           "command": (got.get("command") or {}).get("command_id"),
+                           "status": "requested"}
+    if not a.wait:
+        return out
+
+    def read() -> dict[str, Any]:
+        rows = ctx.client().get("/api/v1/connectors").get("connections") or []
+        return next((c for c in rows if c.get("id") == cid), {})
+
+    def finished(c: dict[str, Any]) -> bool:
+        s = c.get("schedule") or {}
+        return not s.get("syncing") and bool(s.get("last_sync_at")) \
+            and s.get("last_sync_at") != before
+    done = wait_for(ctx, read, finished, "the sync to finish (it runs at the scheduler's next "
+                                         "tick)")
+    sched = done.get("schedule") or {}
+    out.update({"status": sched.get("last_status") or "unknown",
+                "last_sync_at": sched.get("last_sync_at"), **{
+                    k: v for k, v in _row(done).items() if k == "next_sync_at"}})
+    if sched.get("last_status") == "failed":
+        raise CliError(f"the sync of {cid} failed in your deployment", code=FAILED,
+                       error="sync_failed", connection=cid)
+    return out
+
+
+def _show(out: Out, body: dict[str, Any]) -> None:
+    if body.get("action") == "ingest":
+        out.pairs([("knowledge base", body["index"]), ("connection", body["connection"]),
+                   ("status", body["status"]), ("command", body.get("command") or "")])
+        out.note("a sync was already in hand: nothing new was sent" if body["unchanged"] else
+                 "sent to your deployment; it syncs at its scheduler's next tick")
+        return
+    bases = body.get("items")
+    if "upload_id" in body:
+        out.pairs([("uploaded", body.get("key")), ("bytes", body.get("bytes")),
+                   ("deployment", body.get("deployment")), ("indexed", body.get("indexed"))])
+        out.note("the file went straight to your own store; LightHouse never saw it")
+        return
+    if bases is None:
+        out.pairs([(k, v) for k, v in body.items()
+                   if k != "ok" and not isinstance(v, (list, dict))])
+        return
+    out.table(["index", "documents", "chunks", "last refreshed", "health", "backend"],
+              [[b.get("index"), b.get("documents"), b.get("chunks"), b.get("last_refreshed"),
+                (b.get("health") or {}).get("grade"), b.get("backend")] for b in bases])
+    out.note("every index is in the client's own account; nothing is copied to AAL")
+
+
+COMMANDS = (Command("kb", "knowledge bases, their freshness, and ingesting into them",
+                    _configure, kb, _show),)