corethink 1.0.0__py3-none-any.whl

corethink/commands/connection.py

@@ -0,0 +1,1266 @@
+"""`corethink connection`: the workspace's real systems (an HTTP API, an OpenAPI service, an MCP server, a database, your
+own tool code), registered once, tested, and used by environments as live tools.
+
+Admins create, edit and delete connections and set their secrets; members test and check them; everyone sees the
+definitions. Secret values are write-only: typed once (hidden prompt, stdin or an environment variable), stored by the
+Workbench, never shown again.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Any
+from urllib.parse import quote, urlsplit
+
+import typer
+from rich.text import Text
+
+from corethink import output as ui
+from corethink.context import client
+
+app = typer.Typer(
+    help="Your APIs, MCP servers, databases and tool code, as live tools.",
+    no_args_is_help=True,
+)
+secret_app = typer.Typer(help="A connection's secrets: set or clear (values are never shown).", no_args_is_help=True)
+
+KINDS = ("http", "openapi", "mcp", "database", "code")
+KIND_LABEL = {
+    "http": "HTTP API",
+    "openapi": "OpenAPI",
+    "mcp": "MCP server",
+    "database": "Database",
+    "code": "Your own tool code",
+}
+KIND_WHAT = {
+    "http": "An HTTPS API. Each endpoint you describe is a tool.",
+    "openapi": "An HTTPS API with an OpenAPI spec. Pick operations as tools.",
+    "mcp": "An MCP server. Its tools are discovered.",
+    "database": "A read-only database, queried one SELECT at a time.",
+    "code": "Python tool functions in a .zip, run in a sandbox.",
+}
+WRITES_WHAT = {
+    "refuse": "Write tools are never called.",
+    "dry_run": "Write tools return ok without calling your system.",
+    "allow": "Write tools are called. Sandbox or staging only.",
+}
+AUTH_TYPES = ("none", "bearer", "header", "query", "basic")
+DATABASE_TOOLS = ["list_tables", "describe_table", "run_select"]
+MIN_SECRET_CHARS = 6
+MAX_SECRET_BYTES = 64 * 1024
+MAX_PACKAGE_BYTES = 20 * 1024 * 1024
+# fields the Workbench sets itself: never sent back
+SERVER_FIELDS = ("schema", "org", "version", "name")
+
+YES_OPTION = typer.Option(False, "--yes", "-y", help="Do not ask.")
+FROM_OPTION = typer.Option(
+    None,
+    "--from",
+    "-f",
+    help="A JSON definition (plvr.connection/v1); - reads stdin.",
+    show_default=False,
+)
+
+
+# ---- helpers ---------------------------------------------------------------------------------------------------------
+
+
+def _path(name: str, tail: str = "") -> str:
+    return f"/api/v1/connections/{quote(name, safe='')}{tail}"
+
+
+def _connections() -> list[dict[str, Any]]:
+    return (client().get("/api/v1/connections") or {}).get("connections") or []
+
+
+def _resolve(given: str) -> str:
+    """A connection by its name or the start of it: exit 5 when none matches, 2 when several do."""
+    names = [str(row.get("name")) for row in _connections()]
+    if given in names:
+        return given
+    matches = [name for name in names if name.startswith(given.lower())]
+    if len(matches) == 1:
+        return matches[0]
+    if not matches:
+        ui.error(f"No connection named {given}. See `corethink connection list`.")
+        raise typer.Exit(5)
+    ui.error(f"{given} matches more than one connection ({', '.join(sorted(matches))}); give more of the name.")
+    raise typer.Exit(2)
+
+
+def _resolve_job(given: str) -> str:
+    """A run by its ID or the start of it."""
+    given = given.strip().lower()
+    if len(given) == 36:
+        return given
+    jobs = (client().get("/api/v1/harnesses/training-jobs") or {}).get("jobs") or []
+    matches = [str(job.get("job_id")) for job in jobs if str(job.get("job_id", "")).startswith(given)]
+    if len(matches) == 1:
+        return matches[0]
+    if not matches:
+        ui.error(f"No run has an ID starting with {given}. See `corethink train list`.")
+        raise typer.Exit(5)
+    ui.error("More than one run starts with that; give more of its ID.")
+    raise typer.Exit(2)
+
+
+def _read_json(source: str) -> Any:
+    try:
+        text = sys.stdin.read() if source == "-" else Path(source).expanduser().read_text(encoding="utf-8")
+    except OSError as error:
+        ui.error(f"Cannot read {source}: {error.strerror or error}.")
+        raise typer.Exit(2) from None
+    try:
+        return json.loads(text)
+    except ValueError as error:
+        ui.error(f"{source} is not JSON: {error}")
+        raise typer.Exit(2) from None
+
+
+def _load_definition(source: str) -> dict[str, Any]:
+    """A definition from a file: plain, or as `corethink --json connection show` prints it (under "definition")."""
+    data = _read_json(source)
+    if isinstance(data, dict) and isinstance(data.get("definition"), dict) and "record" in data:
+        data = data["definition"]
+    if not isinstance(data, dict):
+        ui.error(f"{source} must hold one JSON object: the connection's definition.")
+        raise typer.Exit(2)
+    return data
+
+
+def _outgoing(definition: dict[str, Any]) -> dict[str, Any]:
+    """What is sent: the definition without the fields the Workbench sets."""
+    return {key: value for key, value in definition.items() if key not in SERVER_FIELDS}
+
+
+def _host_of(address: str | None) -> str:
+    if not address:
+        return ""
+    parts = urlsplit(address)
+    if parts.scheme != "https" or not parts.hostname:
+        return ""
+    return parts.hostname.lower() + (f":{parts.port}" if parts.port else "")
+
+
+def _main_host(definition: dict[str, Any]) -> str:
+    """The host the definition points at, which allowed_hosts must name."""
+    database = definition.get("database") or {}
+    if database.get("host"):
+        port = database.get("port")
+        host = str(database["host"]).lower()
+        return f"{host}:{port}" if port and port != 5432 else host
+    for kind, key in (
+        ("http", "base_url"),
+        ("openapi", "base_url"),
+        ("openapi", "spec_url"),
+        ("mcp", "url"),
+    ):
+        host = _host_of((definition.get(kind) or {}).get(key))
+        if host:
+            return host
+    return ""
+
+
+def _tools_named(definition: dict[str, Any]) -> list[str]:
+    """The tools a definition itself names (endpoints, chosen operations, MCP tools, a database's standard tools)."""
+    names: list[str] = []
+
+    def add(name: Any) -> None:
+        if name and name != "*" and name not in names:
+            names.append(str(name))
+
+    for endpoint in (definition.get("http") or {}).get("endpoints") or []:
+        add(endpoint.get("tool"))
+    for operation in (definition.get("openapi") or {}).get("operations") or []:
+        add(operation)
+    for tool in (definition.get("mcp") or {}).get("tools") or []:
+        add(tool)
+    if definition.get("database"):
+        for tool in DATABASE_TOOLS:
+            add(tool)
+    tools = definition.get("tools") or {}
+    for tool in [*(tools.get("read") or []), *(tools.get("write") or [])]:
+        add(tool)
+    return names
+
+
+def _auth_of(definition: dict[str, Any]) -> dict[str, Any] | None:
+    for kind in ("http", "openapi", "mcp"):
+        block = definition.get(kind)
+        if isinstance(block, dict) and isinstance(block.get("auth"), dict):
+            return block["auth"]
+    return None
+
+
+def _auth_text(auth: dict[str, Any] | None) -> str | None:
+    if not auth:
+        return None
+    kind = auth.get("type") or "none"
+    if kind == "none":
+        return "none"
+    where = {
+        "bearer": "Authorization: Bearer",
+        "header": f"header {auth.get('header') or 'X-Api-Key'}",
+        "query": f"query parameter {auth.get('param')}",
+        "basic": "basic",
+        "oauth_client_credentials": "OAuth client credentials",
+    }.get(kind, kind)
+    return f"{where} · secret {auth.get('secret')}" if auth.get("secret") else where
+
+
+def _target_text(definition: dict[str, Any]) -> str | None:
+    kind = definition.get("kind")
+    block = definition.get(kind) if isinstance(kind, str) else None
+    if not isinstance(block, dict):
+        return None
+    if kind == "http":
+        return block.get("base_url")
+    if kind == "openapi":
+        return block.get("base_url") or block.get("spec_url") or "spec in the definition"
+    if kind == "mcp":
+        return f"{block.get('url')} ({block.get('transport') or 'streamable_http'})"
+    if kind == "database":
+        port = block.get("port") or 5432
+        return f"{block.get('engine')}://{block.get('user')}@{block.get('host')}:{port}/{block.get('database')}"
+    if kind == "code":
+        package = str(block.get("package") or "").split("/")[-1]
+        return f"{block.get('entry')}" + (f" in {package}" if package else " (no package yet)")
+    return None
+
+
+def _mark(ok: Any) -> Text:
+    if ok is None:
+        return Text("–", style="dim")
+    return Text("✓", style="green") if ok else Text("✗", style="red")
+
+
+def _clip(value: Any, size: int = 80) -> str:
+    text = value if isinstance(value, str) else json.dumps(value, ensure_ascii=False, default=str)
+    text = " ".join(str(text).split())
+    return text if len(text) <= size else text[: size - 1] + "…"
+
+
+def _writes_value(value: str | None) -> str | None:
+    if value is None:
+        return None
+    normal = value.strip().lower().replace("-", "_")
+    if normal not in WRITES_WHAT:
+        ui.error("--writes is refuse, dry-run or allow.")
+        raise typer.Exit(2)
+    return normal
+
+
+def _classify(definition: dict[str, Any], reads: list[str] | None, writes: list[str] | None) -> None:
+    """Mark tools read or write (a tool moves from the other list)."""
+    tools = definition.setdefault("tools", {})
+    read = list(tools.get("read") or [])
+    write = list(tools.get("write") or [])
+    for name in reads or []:
+        if name in write:
+            write.remove(name)
+        if name not in read:
+            read.append(name)
+    for name in writes or []:
+        if name in read:
+            read.remove(name)
+        if name not in write:
+            write.append(name)
+    tools["read"], tools["write"] = read, write
+
+
+def _unclassified(definition: dict[str, Any]) -> list[str]:
+    tools = definition.get("tools") or {}
+    known = set(tools.get("read") or []) | set(tools.get("write") or [])
+    return [name for name in _tools_named(definition) if name not in known]
+
+
+def _upload_package(name: str, package: Path) -> str:
+    """Send a code package (.zip) straight to storage; the upload's ID, used when the definition is saved."""
+    if not package.is_file():
+        ui.error(f"{package} is not a file.")
+        raise typer.Exit(2)
+    if package.suffix.lower() != ".zip":
+        ui.error("A package is a .zip of your module and its files (dependencies vendored in).")
+        raise typer.Exit(2)
+    data = package.read_bytes()
+    if not data or len(data) > MAX_PACKAGE_BYTES:
+        ui.error("A package is a .zip of at most 20 MB.")
+        raise typer.Exit(2)
+    target = client().post(_path(name, "/package"), {"size": len(data)})
+    file = target.get("file") or {}
+    with ui.err.status(f"Uploading {package.name}…", spinner="dots"):
+        client().put_signed(
+            str(file.get("url")),
+            data,
+            headers=file.get("headers") or {"content-type": "application/zip"},
+            method=str(file.get("method") or "PUT"),
+        )
+    return str(target["upload"])
+
+
+def _next_steps(name: str, view: dict[str, Any]) -> None:
+    unset = [secret for secret, status in (view.get("secrets") or {}).items() if not (status or {}).get("set")]
+    for secret in unset:
+        ui.info(f"Set its secret: corethink connection secret set {name} {secret}")
+    ui.info(f"Test it: corethink connection test {name}")
+
+
+# ---- list and show ---------------------------------------------------------------------------------------------------
+
+
+@app.command("list")
+def list_(
+    job: str = typer.Option(None, "--job", help="Only the connections this run was given, with their versions."),
+) -> None:
+    """Your workspace's connections.
+
+    Example: corethink connection list
+    """
+    if job:
+        job_id = _resolve_job(job)
+        given = (client().get("/api/v1/connections", job=job_id) or {}).get("connections") or {}
+        rows = [{"name": name, "version": version} for name, version in sorted(given.items())]
+
+        def human_job() -> None:
+            ui.table(
+                rows,
+                [("Name", "name"), ("Version", lambda r: f"v{r['version']}")],
+                empty="This run used no connections.",
+            )
+
+        ui.emit({"job": job_id, "connections": given}, human_job)
+        return
+
+    rows = _connections()
+
+    def last_check(row: dict[str, Any]) -> Text | str:
+        check = row.get("last_check")
+        if not check:
+            return "never"
+        return _mark(check.get("ok")) + Text(f" {ui.ago(check.get('at'))}")
+
+    def human() -> None:
+        ui.table(
+            rows,
+            [
+                ("Name", "name"),
+                ("Kind", lambda r: KIND_LABEL.get(r.get("kind"), r.get("kind"))),
+                ("Version", lambda r: f"v{r.get('version')}"),
+                (
+                    "Tools",
+                    lambda r: (
+                        f"{len((r.get('tools') or {}).get('read') or [])} read · "
+                        f"{len((r.get('tools') or {}).get('write') or [])} write"
+                    ),
+                ),
+                ("Writes", lambda r: str(r.get("writes") or "refuse").replace("_", "-")),
+                ("Last check", last_check),
+                ("Updated", lambda r: ui.ago(r.get("updated_at"))),
+            ],
+            empty="No connections yet. Make one with `corethink connection create`.",
+        )
+
+    ui.emit(rows, human)
+
+
+@app.command("show")
+def show(
+    name: str = typer.Argument(..., help="The connection (its name, or the start of it)."),
+    version: int = typer.Option(None, "--version", min=1, help="An earlier version (default: the newest)."),
+    definition_only: bool = typer.Option(
+        False,
+        "--definition",
+        help="Print only the definition as JSON (to edit and save with `update --from`).",
+    ),
+) -> None:
+    """A connection: what it reaches, its tools, secrets (set or not) and versions.
+
+    Example: corethink connection show orders-api --definition > orders.json
+    """
+    name = _resolve(name)
+    view = client().get(_path(name), version=version) or {}
+    definition = view.get("definition") or {}
+    if definition_only:
+        ui.print_json(definition)
+        return
+    record = view.get("record") or {}
+    tools = definition.get("tools") or {}
+    writes = str(definition.get("writes") or "refuse")
+
+    def human() -> None:
+        unclassified = _unclassified(definition)
+        secrets = view.get("secrets") or {}
+        secret_text = (
+            ", ".join(
+                f"{secret} ({'set · ' + ui.when(status.get('updated_at')) if status.get('set') else 'not set'})"
+                for secret, status in sorted(secrets.items())
+            )
+            or "none"
+        )
+        versions = [str(entry.get("version")) for entry in view.get("versions") or []]
+        kind = str(definition.get("kind"))
+        ui.fields(
+            [
+                ("Name", definition.get("name") or name),
+                ("Kind", f"{KIND_LABEL.get(kind, kind)} · {KIND_WHAT.get(kind, '')}".rstrip(" ·")),
+                ("Description", definition.get("description")),
+                ("Version", f"v{definition.get('version') or record.get('version')}"),
+                (
+                    "Updated",
+                    f"{ui.when(record.get('updated_at'))} by {record.get('updated_by') or '—'}",
+                ),
+                ("Target", _target_text(definition)),
+                ("Auth", _auth_text(_auth_of(definition))),
+                ("Reaches", ", ".join(definition.get("allowed_hosts") or []) or None),
+                ("Read tools", ", ".join(tools.get("read") or []) or "none"),
+                ("Write tools", ", ".join(tools.get("write") or []) or "none"),
+                (
+                    "Unclassified",
+                    f"{', '.join(unclassified)} (count as writes)" if unclassified else None,
+                ),
+                ("Writes", f"{writes.replace('_', '-')}: {WRITES_WHAT.get(writes, '')}"),
+                (
+                    "Secrets",
+                    secret_text if view.get("secretsAvailable", True) else "cannot be stored here",
+                ),
+                ("Used by", ", ".join(view.get("usedBy") or []) or "no environment"),
+                ("Versions", ", ".join(versions) if len(versions) > 1 else None),
+            ]
+        )
+
+    ui.emit(view, human)
+
+
+# ---- create, update, delete ------------------------------------------------------------------------------------------
+
+
+def _parse_endpoint(text: str) -> dict[str, Any]:
+    """`get_order=GET /orders/{order_id}` → an HTTP endpoint."""
+    tool, sep, route = text.partition("=")
+    if not sep or not tool.strip():
+        ui.error(f"--endpoint {text}: use TOOL=METHOD /path, e.g. get_order=GET /orders/{{order_id}}.")
+        raise typer.Exit(2)
+    parts = route.split()
+    if len(parts) == 1:
+        method, path = "GET", parts[0]
+    elif len(parts) == 2:
+        method, path = parts[0].upper(), parts[1]
+    else:
+        ui.error(f"--endpoint {text}: use TOOL=METHOD /path.")
+        raise typer.Exit(2)
+    if not path.startswith("/"):
+        ui.error(f"--endpoint {text}: the path starts with / (e.g. /orders/{{order_id}}).")
+        raise typer.Exit(2)
+    return {"tool": tool.strip(), "method": method, "path": path}
+
+
+@app.command("create")
+def create(
+    name: str = typer.Argument(None, help="Its name: lowercase letters, digits and -. Or give it in --from."),
+    source: str = FROM_OPTION,
+    kind: str = typer.Option(None, "--kind", "-k", help="http, openapi, mcp, database or code."),
+    description: str = typer.Option(None, "--description", help="What it is, in a line."),
+    url: str = typer.Option(
+        None,
+        "--url",
+        help="HTTP API: its base URL. MCP: the server's URL. OpenAPI: the spec's https:// address.",
+        rich_help_panel="Where it is",
+    ),
+    spec: Path = typer.Option(
+        None,
+        "--spec",
+        help="OpenAPI: the spec as a JSON file (instead of --url).",
+        rich_help_panel="Where it is",
+    ),
+    base_url: str = typer.Option(
+        None,
+        "--base-url",
+        help="OpenAPI: the API's address when the spec does not say.",
+        rich_help_panel="Where it is",
+    ),
+    endpoints: list[str] = typer.Option(
+        None,
+        "--endpoint",
+        "-e",
+        help="HTTP API: a tool, as TOOL=METHOD /path (repeatable).",
+        rich_help_panel="Where it is",
+    ),
+    operations: list[str] = typer.Option(
+        None,
+        "--operation",
+        help="OpenAPI: an operationId to use as a tool (repeatable).",
+        rich_help_panel="Where it is",
+    ),
+    mcp_tools: list[str] = typer.Option(
+        None,
+        "--tool",
+        help="MCP: a tool to use (repeatable; default every tool).",
+        rich_help_panel="Where it is",
+    ),
+    transport: str = typer.Option(
+        None,
+        "--transport",
+        help="MCP: streamable_http (default) or sse.",
+        rich_help_panel="Where it is",
+    ),
+    allow_hosts: list[str] = typer.Option(
+        None,
+        "--allow-host",
+        help="A host it may reach, host or host:port (repeatable; default: the host it points at).",
+        rich_help_panel="Where it is",
+    ),
+    auth: str = typer.Option(
+        None,
+        "--auth",
+        help="none, bearer, header, query or basic (default bearer with --secret).",
+        rich_help_panel="Auth",
+    ),
+    secret: str = typer.Option(
+        None,
+        "--secret",
+        help="The name of the secret holding the token or key, e.g. api_key (its value is set with `secret set`).",
+        rich_help_panel="Auth",
+    ),
+    auth_header: str = typer.Option(
+        None,
+        "--auth-header",
+        help="header auth: the header (default X-Api-Key).",
+        rich_help_panel="Auth",
+    ),
+    auth_prefix: str = typer.Option(
+        None, "--auth-prefix", help="header auth: text before the value.", rich_help_panel="Auth"
+    ),
+    auth_param: str = typer.Option(
+        None, "--auth-param", help="query auth: the query parameter.", rich_help_panel="Auth"
+    ),
+    username: str = typer.Option(None, "--username", help="basic auth: the user name.", rich_help_panel="Auth"),
+    engine: str = typer.Option(None, "--engine", help="Database: postgres.", rich_help_panel="Database"),
+    host: str = typer.Option(None, "--host", help="Database: its host.", rich_help_panel="Database"),
+    port: int = typer.Option(None, "--port", help="Database: its port (default 5432).", rich_help_panel="Database"),
+    database: str = typer.Option(None, "--database", help="Database: its name.", rich_help_panel="Database"),
+    user: str = typer.Option(
+        None, "--user", help="Database: the user (read-only, ideally).", rich_help_panel="Database"
+    ),
+    password_secret: str = typer.Option(
+        None,
+        "--password-secret",
+        help="Database: the secret holding the password (default db_password).",
+        rich_help_panel="Database",
+    ),
+    schemas: list[str] = typer.Option(
+        None,
+        "--schema",
+        help="Database: a schema it may query (repeatable; default public).",
+        rich_help_panel="Database",
+    ),
+    package: Path = typer.Option(
+        None,
+        "--package",
+        help="Code: the .zip of your tool functions (at most 20 MB).",
+        rich_help_panel="Code",
+    ),
+    entry: str = typer.Option(
+        None,
+        "--entry",
+        help="Code: module:NAME, a list of tool functions (default tools:TOOLS).",
+        rich_help_panel="Code",
+    ),
+    code_secrets: list[str] = typer.Option(
+        None,
+        "--code-secret",
+        help="Code: a secret its functions receive (repeatable).",
+        rich_help_panel="Code",
+    ),
+    reads: list[str] = typer.Option(
+        None,
+        "--read",
+        help="Mark a tool read: it only reads (repeatable).",
+        rich_help_panel="Tools",
+    ),
+    writes_tools: list[str] = typer.Option(
+        None,
+        "--write",
+        help="Mark a tool write: it changes something (repeatable).",
+        rich_help_panel="Tools",
+    ),
+    writes: str = typer.Option(
+        None,
+        "--writes",
+        help="Write tools in training: refuse (default), dry-run or allow.",
+        rich_help_panel="Tools",
+    ),
+    timeout: float = typer.Option(
+        None,
+        "--timeout",
+        help="Seconds to wait for an answer (default 20).",
+        rich_help_panel="Tools",
+    ),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Print the definition that would be sent, and stop."),
+) -> None:
+    """Make a connection (admins) from flags, a JSON definition (--from), or both (flags win).
+
+    Tools are read or write: read tools are called freely in tests and training; write tools follow --writes, and a tool in neither list counts as a write. Secrets are named here and set afterwards with `secret set`.
+
+    Examples:
+      corethink connection create orders-api --kind http --url https://api.example.com --secret api_key \\
+          -e "get_order=GET /orders/{order_id}" --read get_order
+      corethink connection create docs --kind mcp --url https://mcp.example.com/mcp --auth none
+      corethink connection create crm --from crm.json
+      corethink connection create my-tools --kind code --package tools.zip --entry tools:TOOLS
+    """
+    definition: dict[str, Any] = _load_definition(source) if source else {}
+    name = name or definition.get("name")
+    if not name:
+        ui.error("Name the connection: corethink connection create NAME …")
+        raise typer.Exit(2)
+    kind = (kind or definition.get("kind") or "").lower()
+    if kind not in KINDS:
+        ui.error("Choose a kind with --kind: http, openapi, mcp, database or code.")
+        raise typer.Exit(2)
+    definition = _outgoing(definition)
+    definition["name"] = name
+    definition["kind"] = kind
+    if description is not None:
+        definition["description"] = description
+    block: dict[str, Any] = dict(definition.get(kind) or {})
+
+    if kind in ("http", "openapi", "mcp"):
+        given = dict(block.get("auth") or {})
+        if auth or secret or "type" not in given:
+            chosen = (auth or ("bearer" if secret else given.get("type") or "none")).lower()
+            if chosen not in AUTH_TYPES:
+                ui.error(f"--auth is one of {', '.join(AUTH_TYPES)} (OAuth: use --from).")
+                raise typer.Exit(2)
+            given["type"] = chosen
+        if given.get("type") != "none" and secret:
+            given["secret"] = secret
+        elif given.get("type") != "none" and not given.get("secret"):
+            given["secret"] = "api_key"
+        for key, value in (
+            ("header", auth_header),
+            ("prefix", auth_prefix),
+            ("param", auth_param),
+            ("username", username),
+        ):
+            if value is not None:
+                given[key] = value
+        block["auth"] = given
+
+    if kind == "http":
+        if url:
+            block["base_url"] = url
+        if endpoints:
+            block["endpoints"] = [
+                *(block.get("endpoints") or []),
+                *(_parse_endpoint(e) for e in endpoints),
+            ]
+        if not block.get("base_url") or not block.get("endpoints"):
+            ui.error("An HTTP API needs --url (its base URL) and at least one --endpoint TOOL=METHOD /path.")
+            raise typer.Exit(2)
+    elif kind == "openapi":
+        if spec:
+            loaded = _read_json(str(spec))
+            if not isinstance(loaded, dict):
+                ui.error(f"{spec} is not an OpenAPI spec (a JSON object).")
+                raise typer.Exit(2)
+            block["spec"] = loaded
+            block.pop("spec_url", None)
+        elif url:
+            block["spec_url"] = url
+            block.pop("spec", None)
+        if base_url:
+            block["base_url"] = base_url
+        if operations:
+            block["operations"] = list(dict.fromkeys([*(block.get("operations") or []), *operations]))
+        if not block.get("spec") and not block.get("spec_url"):
+            ui.error("An OpenAPI connection needs its spec: --spec FILE.json or --url https://…/openapi.json.")
+            raise typer.Exit(2)
+    elif kind == "mcp":
+        if url:
+            block["url"] = url
+        if transport:
+            block["transport"] = transport.replace("-", "_")
+        if mcp_tools:
+            block["tools"] = list(mcp_tools)
+        if not block.get("url"):
+            ui.error("An MCP connection needs the server's --url.")
+            raise typer.Exit(2)
+    elif kind == "database":
+        for key, value in (
+            ("engine", engine),
+            ("host", host),
+            ("port", port),
+            ("database", database),
+            ("user", user),
+        ):
+            if value is not None:
+                block[key] = value
+        block.setdefault("engine", "postgres")
+        block["password_secret"] = password_secret or block.get("password_secret") or "db_password"
+        if schemas:
+            gate = dict(block.get("sql_gate") or {})
+            gate["allowed_schemas"] = list(schemas)
+            block["sql_gate"] = gate
+        missing = [
+            flag
+            for flag, key in (("--host", "host"), ("--database", "database"), ("--user", "user"))
+            if not block.get(key)
+        ]
+        if missing:
+            ui.error(f"A database connection needs {', '.join(missing)}.")
+            raise typer.Exit(2)
+        tools = definition.setdefault("tools", {})
+        if not tools.get("read") and not tools.get("write"):
+            tools["read"] = list(DATABASE_TOOLS)
+    elif kind == "code":
+        if entry:
+            block["entry"] = entry
+        block.setdefault("entry", "tools:TOOLS")
+        if code_secrets:
+            block["secrets"] = list(dict.fromkeys([*(block.get("secrets") or []), *code_secrets]))
+        if not package and not block.get("upload"):
+            ui.error("A code connection needs its package: --package tools.zip.")
+            raise typer.Exit(2)
+    definition[kind] = block
+
+    _classify(definition, reads, writes_tools)
+    mode = _writes_value(writes)
+    if mode:
+        definition["writes"] = mode
+    if timeout is not None:
+        definition["timeout_s"] = timeout
+    if allow_hosts:
+        definition["allowed_hosts"] = list(dict.fromkeys([*(definition.get("allowed_hosts") or []), *allow_hosts]))
+    if kind != "code" and not definition.get("allowed_hosts"):
+        main = _main_host(definition)
+        if main:
+            definition["allowed_hosts"] = [main]
+
+    if dry_run:
+        ui.print_json(definition)
+        return
+    if kind == "code" and package:
+        definition["code"]["upload"] = _upload_package(name, package)
+    view = client().post("/api/v1/connections", definition)
+    saved = view.get("definition") or {}
+
+    def human() -> None:
+        ui.success(f"Created {name} ({KIND_LABEL[kind]}, v{saved.get('version', 1)}).")
+        unclassified = _unclassified(saved)
+        if unclassified:
+            ui.warn(
+                f"Not classified, so treated as writes: {', '.join(unclassified)}. "
+                f"Mark reads: corethink connection update {name} --read TOOL"
+            )
+        _next_steps(name, view)
+
+    ui.emit(view, human)
+
+
+@app.command("update")
+def update(
+    name: str = typer.Argument(..., help="The connection."),
+    source: str = FROM_OPTION,
+    description: str = typer.Option(None, "--description", help="A new description."),
+    reads: list[str] = typer.Option(None, "--read", help="Mark a tool read (repeatable)."),
+    writes_tools: list[str] = typer.Option(None, "--write", help="Mark a tool write (repeatable)."),
+    writes: str = typer.Option(None, "--writes", help="Write tools in training: refuse, dry-run or allow."),
+    allow_hosts: list[str] = typer.Option(None, "--allow-host", help="Another host it may reach (repeatable)."),
+) -> None:
+    """Save a connection's next version (admins).
+
+    A whole definition from --from, or quick changes on the newest. A definition saved from `show --definition` keeps its version: if someone saved another since, the save is refused instead of overwriting theirs.
+
+    Examples:
+      corethink connection show orders-api --definition > orders.json   # edit it, then:
+      corethink connection update orders-api --from orders.json
+      corethink connection update orders-api --read list_orders --write refund_order
+    """
+    name = _resolve(name)
+    if not (source or description is not None or reads or writes_tools or writes or allow_hosts):
+        ui.error("Nothing to change: give --from FILE, or --description, --read, --write, --writes, --allow-host.")
+        raise typer.Exit(2)
+    current = client().get(_path(name)) or {}
+    base = int((current.get("record") or {}).get("version") or (current.get("definition") or {}).get("version") or 0)
+    if source:
+        definition = _load_definition(source)
+        if isinstance(definition.get("version"), int):
+            base = definition["version"]
+        if definition.get("name") not in (None, name):
+            ui.error("A connection cannot be renamed: make a new one.")
+            raise typer.Exit(2)
+    else:
+        definition = dict(current.get("definition") or {})
+    definition = _outgoing(definition)
+    if description is not None:
+        definition["description"] = description
+    _classify(definition, reads, writes_tools)
+    mode = _writes_value(writes)
+    if mode:
+        definition["writes"] = mode
+    if allow_hosts:
+        definition["allowed_hosts"] = list(dict.fromkeys([*(definition.get("allowed_hosts") or []), *allow_hosts]))
+    view = client().put(_path(name), {**definition, "base": base})
+    saved = view.get("definition") or {}
+    ui.emit(view, lambda: ui.success(f"Saved {name} as v{saved.get('version')}."))
+
+
+@app.command("delete")
+def delete(
+    name: str = typer.Argument(..., help="The connection."),
+    yes: bool = YES_OPTION,
+) -> None:
+    """Delete a connection, every version and its secrets (admins).
+
+    Refused while an environment's scoring uses it.
+    """
+    name = _resolve(name)
+    ui.confirm(f"Delete {name}, every version and its secrets? This cannot be undone.", yes=yes)
+    done = client().delete(_path(name)) or {"deleted": name}
+    ui.emit(done, lambda: ui.success(f"Deleted {name}."))
+
+
+@app.command("upload")
+def upload(
+    name: str = typer.Argument(..., help="A code connection."),
+    package: Path = typer.Argument(..., help="The .zip of your tool functions (at most 20 MB)."),
+    entry: str = typer.Option(None, "--entry", help="A new entry, module:NAME (default: as it is)."),
+) -> None:
+    """Upload a code connection's new package (admins) and save it as the next version.
+
+    The package holds your module and everything it imports (nothing is installed). A new code connection is made with `create --kind code --package FILE`.
+
+    Example: corethink connection upload my-tools dist/tools.zip
+    """
+    name = _resolve(name)
+    current = client().get(_path(name)) or {}
+    definition = _outgoing(dict(current.get("definition") or {}))
+    if definition.get("kind") != "code":
+        ui.error(f"{name} is not a code connection: only those have a package.")
+        raise typer.Exit(2)
+    upload_id = _upload_package(name, package)
+    code = dict(definition.get("code") or {})
+    code["upload"] = upload_id
+    if entry:
+        code["entry"] = entry
+    definition["code"] = code
+    base = int((current.get("record") or {}).get("version") or 0)
+    view = client().put(_path(name), {**definition, "base": base})
+    saved = view.get("definition") or {}
+    ui.emit(view, lambda: ui.success(f"Uploaded {package.name}: {name} is now v{saved.get('version')}."))
+
+
+# ---- secrets ---------------------------------------------------------------------------------------------------------
+
+
+@secret_app.command("list")
+def secret_list(name: str = typer.Argument(..., help="The connection.")) -> None:
+    """The secrets a connection uses, and whether each is set (never their values)."""
+    name = _resolve(name)
+    view = client().get(_path(name)) or {}
+    rows = [{"secret": key, **(value or {})} for key, value in sorted((view.get("secrets") or {}).items())]
+
+    def human() -> None:
+        ui.table(
+            rows,
+            [
+                ("Secret", "secret"),
+                (
+                    "State",
+                    lambda r: Text("set", style="green") if r.get("set") else Text("not set", style="yellow"),
+                ),
+                ("Updated", lambda r: ui.when(r.get("updated_at")) if r.get("set") else None),
+            ],
+            empty=f"{name} uses no secrets.",
+        )
+
+    ui.emit(rows, human)
+
+
+@secret_app.command("set")
+def secret_set(
+    name: str = typer.Argument(..., help="The connection."),
+    secret: str = typer.Argument(..., help="The secret's name, e.g. api_key (see `connection show`)."),
+    stdin: bool = typer.Option(False, "--stdin", help="Read the value from stdin instead of a hidden prompt."),
+    from_env: str = typer.Option(None, "--from-env", help="Read the value from this environment variable."),
+) -> None:
+    """Set a secret's value (admins).
+
+    Typed at a hidden prompt, or read from stdin or an environment variable; never as an argument. It is stored by the Workbench and never shown again.
+
+    Examples:
+      corethink connection secret set orders-api api_key
+      op read op://vault/orders/key | corethink connection secret set orders-api api_key --stdin
+    """
+    name = _resolve(name)
+    if from_env:
+        value = os.environ.get(from_env)
+        if value is None:
+            ui.error(f"{from_env} is not set.")
+            raise typer.Exit(2)
+    elif stdin:
+        value = sys.stdin.read().rstrip("\r\n")
+    elif sys.stdin.isatty():
+        value = typer.prompt(f"Value of {secret}", hide_input=True)
+    else:
+        ui.error("No terminal to type the value in: pipe it with --stdin, or use --from-env VAR.")
+        raise typer.Exit(2)
+    if len(value) < MIN_SECRET_CHARS:
+        ui.error(
+            f"A secret has at least {MIN_SECRET_CHARS} characters (shorter ones cannot be kept out of logs safely)."
+        )
+        raise typer.Exit(2)
+    if len(value.encode()) > MAX_SECRET_BYTES:
+        ui.error("A secret is at most 64 KB.")
+        raise typer.Exit(2)
+    status = client().put(_path(name, f"/secrets/{quote(secret, safe='')}"), {"value": value})
+    del value
+    ui.emit(status, lambda: ui.success(f"Set {secret} on {name}."))
+
+
+@secret_app.command("clear")
+def secret_clear(
+    name: str = typer.Argument(..., help="The connection."),
+    secret: str = typer.Argument(..., help="The secret's name."),
+    yes: bool = YES_OPTION,
+) -> None:
+    """Remove a secret's value (admins): calls that need it fail until it is set again."""
+    name = _resolve(name)
+    ui.confirm(f"Clear {secret} on {name}? Calls that need it fail until it is set again.", yes=yes)
+    status = client().delete(_path(name, f"/secrets/{quote(secret, safe='')}"))
+    ui.emit(status, lambda: ui.success(f"Cleared {secret} on {name}."))
+
+
+# ---- test, discover, check -------------------------------------------------------------------------------------------
+
+
+def _samples(given: list[str] | None) -> list[dict[str, Any]]:
+    samples: list[dict[str, Any]] = []
+    for item in given or []:
+        tool, sep, text = item.partition("=")
+        if not sep or not tool.strip():
+            ui.error(f'--sample {item}: use TOOL=JSON, e.g. get_order=\'{{"order_id": "A-1001"}}\'.')
+            raise typer.Exit(2)
+        try:
+            parsed = json.loads(text)
+        except ValueError:
+            ui.error(f"--sample {tool}: the arguments are not JSON.")
+            raise typer.Exit(2) from None
+        calls = parsed if isinstance(parsed, list) else [parsed]
+        if not calls or not all(isinstance(call, dict) for call in calls):
+            ui.error(f"--sample {tool}: give a JSON object of arguments (or a list of them, one call each).")
+            raise typer.Exit(2)
+        samples.extend({"tool": tool.strip(), "args": call} for call in calls)
+    if len(samples) > 20:
+        ui.error("Give at most 20 sample calls.")
+        raise typer.Exit(2)
+    return samples
+
+
+def _show_report(report: dict[str, Any], definition: dict[str, Any]) -> None:
+    """A test's or discovery's report, as the console shows it."""
+    missing = report.get("missing_secrets") or []
+    if missing:
+        ui.warn(
+            f"Not set yet: {', '.join(missing)}. Set {'it' if len(missing) == 1 else 'them'} with "
+            f"`corethink connection secret set {definition.get('name') or 'NAME'} {missing[0]}` and test again."
+        )
+    lines: list[Text] = []
+    if report.get("reachable") is not None:
+        status = f" · HTTP {report['status']}" if report.get("status") is not None else ""
+        lines.append(
+            _mark(report["reachable"]) + Text(f" {'Reachable' if report['reachable'] else 'Not reachable'}{status}")
+        )
+    if report.get("auth") is not None:
+        auth = report["auth"]
+        word = {"ok": "Authenticated", "failed": "Authentication failed"}.get(auth, "Authentication not checked")
+        lines.append(_mark(None if auth == "not_checked" else auth == "ok") + Text(f" {word}"))
+    for line in lines:
+        ui.out.print(line)
+    if report.get("detail"):
+        ui.out.print(Text(str(report["detail"]), style="dim"))
+    for text in dict.fromkeys([*(report.get("errors") or []), *(report.get("problems") or [])]):
+        ui.out.print(Text(str(text), style="red"))
+    for text in report.get("warnings") or []:
+        ui.out.print(Text(str(text), style="yellow"))
+    tools = report.get("tools")
+    if tools:
+        _tools_table(tools, report, definition)
+    samples = report.get("samples") or []
+    if samples:
+        ui.heading("Sample calls")
+        for sample in samples:
+            line = _mark(bool(sample.get("ok"))) + Text(f" {sample.get('tool')}")
+            if sample.get("args") is not None:
+                line += Text(f" {_clip(sample['args'], 120)}", style="dim")
+            if sample.get("status") is not None:
+                line += Text(f" · {sample['status']}")
+            if sample.get("latency_ms") is not None:
+                line += Text(f" · {round(float(sample['latency_ms']))} ms")
+            if sample.get("error"):
+                line += Text(f" · {sample['error']}", style="red")
+            ui.out.print(line)
+            result = sample.get("result", sample.get("result_preview"))
+            if result is not None:
+                ui.out.print(Text("  " + _clip(result, 300), style="dim"))
+    for skipped in report.get("skipped_samples") or []:
+        ui.out.print(Text(f"{skipped.get('tool')} not called: {skipped.get('why')}", style="dim"))
+    if report.get("ok") is not None:
+        if report["ok"]:
+            ui.success("The connection works.")
+        else:
+            ui.error("The connection does not work yet.")
+
+
+def _tools_table(tools: list[dict[str, Any]], report: dict[str, Any], definition: dict[str, Any]) -> None:
+    read = set((definition.get("tools") or {}).get("read") or [])
+    unclassified = set(report.get("unclassified") or [])
+
+    def access(tool: dict[str, Any]) -> Text:
+        kind = tool.get("access") or ("read" if tool.get("name") in read else "write")
+        label = Text(kind, style="green" if kind == "read" else "yellow")
+        if tool.get("name") in unclassified:
+            label += Text(" (unclassified)", style="dim")
+        return label
+
+    ui.table(
+        tools,
+        [
+            ("Tool", "name"),
+            ("Access", access),
+            (
+                "System says",
+                lambda t: (
+                    t.get("suggested_access")
+                    if t.get("suggested_access") and t.get("suggested_access") != (t.get("access") or "")
+                    else None
+                ),
+            ),
+            ("Description", lambda t: _clip(t.get("description") or "", 90) or None),
+        ],
+        title=f"Tools ({len(tools)})",
+    )
+    if unclassified:
+        ui.warn(
+            f"Not classified, so treated as writes: {', '.join(sorted(unclassified))}. Mark reads: "
+            f"corethink connection update {definition.get('name') or 'NAME'} --read TOOL"
+        )
+
+
+@app.command("test")
+def test(
+    name: str = typer.Argument(..., help="The connection."),
+    samples: list[str] = typer.Option(
+        None,
+        "--sample",
+        "-s",
+        help="A sample call of a read tool, TOOL=JSON arguments (repeatable; a JSON list makes one call each).",
+    ),
+    source: str = typer.Option(
+        None,
+        "--from",
+        "-f",
+        help="Test an edited definition (JSON file) before saving it (admins).",
+    ),
+) -> None:
+    """Test a connection: reachable, credentials, tools, and sample calls of read tools.
+
+    Write tools are never called. Sample calls that all answer are repeated by every check from then on. Exits 1 when the connection does not work.
+
+    Example: corethink connection test orders-api -s 'get_order={"order_id": "A-1001"}'
+    """
+    name = _resolve(name)
+    body: dict[str, Any] = {}
+    picked = _samples(samples)
+    if picked:
+        body["samples"] = picked
+    draft = _outgoing(_load_definition(source)) if source else None
+    if draft is not None:
+        body["definition"] = draft
+    with ui.err.status(f"Testing {name}…", spinner="dots"):
+        report = client().post(_path(name, ":test"), body) or {}
+    definition = draft or (client().get(_path(name)) or {}).get("definition") or {}
+    definition = {**definition, "name": name}
+    ui.emit(report, lambda: _show_report(report, definition))
+    if report.get("ok") is False:
+        raise typer.Exit(1)
+
+
+@app.command("discover")
+def discover(
+    name: str = typer.Argument(..., help="The connection."),
+    source: str = typer.Option(None, "--from", "-f", help="Discover with an edited definition (JSON file; admins)."),
+) -> None:
+    """The tools a connection exposes, and whether each counts as read or write.
+
+    A tool in neither list of the definition counts as a write. Mark reads with `update NAME --read TOOL`.
+
+    Example: corethink connection discover docs-mcp
+    """
+    name = _resolve(name)
+    draft = _outgoing(_load_definition(source)) if source else None
+    with ui.err.status(f"Asking {name} for its tools…", spinner="dots"):
+        report = client().post(_path(name, ":discover"), {"definition": draft} if draft is not None else {}) or {}
+    definition = draft or (client().get(_path(name)) or {}).get("definition") or {}
+    definition = {**definition, "name": name}
+    tools = report.get("tools") or []
+
+    def human() -> None:
+        if report.get("missing_secrets"):
+            ui.warn(f"Not set yet: {', '.join(report['missing_secrets'])}.")
+        for text in dict.fromkeys([*(report.get("errors") or []), *(report.get("problems") or [])]):
+            ui.error(str(text))
+        if tools:
+            _tools_table(tools, report, definition)
+        else:
+            ui.info("No tools found.")
+
+    ui.emit(report, human)
+
+
+@app.command("check")
+def check(name: str = typer.Argument(..., help="The connection.")) -> None:
+    """Check a connection's saved version now and keep the result.
+
+    Its remembered sample calls are made too. Exits 1 when the check fails.
+    """
+    name = _resolve(name)
+    with ui.err.status(f"Checking {name}…", spinner="dots"):
+        result = (client().post(_path(name, ":check"), {}) or {}).get("check") or {}
+
+    def human() -> None:
+        head = f"v{result.get('version')} · {result.get('ms', 0)} ms"
+        if result.get("ok"):
+            ui.success(f"{name} works ({head}).")
+        else:
+            ui.error(f"{name} failed ({head}): {result.get('error') or 'see below'}")
+        if result.get("reachable") is not None:
+            ui.out.print(_mark(result["reachable"]) + Text(" Reachable" if result["reachable"] else " Not reachable"))
+        if result.get("auth"):
+            ui.out.print(
+                _mark(None if result["auth"] == "not_checked" else result["auth"] == "ok")
+                + Text(f" Auth {result['auth']}")
+            )
+        for tool in result.get("tools") or []:
+            ui.out.print(_mark(tool.get("ok")) + Text(f" {tool.get('tool')} · {tool.get('ms')} ms"))
+
+    ui.emit(result, human)
+    if not result.get("ok"):
+        raise typer.Exit(1)
+
+
+@app.command("checks")
+def checks(
+    name: str = typer.Argument(..., help="The connection."),
+    limit: int = typer.Option(10, "--limit", "-n", min=1, help="How many of the newest checks."),
+) -> None:
+    """A connection's recent checks, newest first, and how often it is checked."""
+    name = _resolve(name)
+    data = client().get(_path(name, "/checks")) or {}
+    rows = list(reversed(data.get("checks") or []))[:limit]
+
+    def human() -> None:
+        ui.table(
+            rows,
+            [
+                ("When", lambda r: ui.when(r.get("at"))),
+                (
+                    "Result",
+                    lambda r: _mark(r.get("ok")) + Text(" works" if r.get("ok") else " failed"),
+                ),
+                ("Time", lambda r: f"{r.get('ms')} ms"),
+                ("Version", lambda r: f"v{r.get('version')}"),
+                ("By", "by"),
+                ("Why", lambda r: _clip(r.get("error") or "", 80) or None),
+            ],
+            empty="Not checked yet. Check it now: corethink connection check " + name,
+        )
+        if data.get("every_minutes"):
+            ui.info(f"Checked every {data['every_minutes']} minutes.")
+        if data.get("tools"):
+            ui.info(f"A check calls: {', '.join(data['tools'])}.")
+
+    ui.emit(data, human)
+
+
+@app.command("live")
+def live(name: str = typer.Argument(..., help="The connection.")) -> None:
+    """Live calls of your recent runs through a connection: each tool's calls, failures and latency."""
+    name = _resolve(name)
+    data = client().get(_path(name, "/live")) or {}
+
+    def human() -> None:
+        ui.table(
+            data.get("tools") or [],
+            [
+                ("Tool", "tool"),
+                ("Calls", "calls"),
+                ("Failed", "failed"),
+                ("p50", lambda r: f"{r.get('p50')} ms" if r.get("p50") is not None else None),
+                ("p95", lambda r: f"{r.get('p95')} ms" if r.get("p95") is not None else None),
+            ],
+            empty="No live calls in your recent runs.",
+        )
+
+    ui.emit(data, human)
+
+
+@app.command("calls")
+def calls(
+    name: str = typer.Argument(..., help="The connection."),
+    job: str = typer.Option(..., "--job", "-j", help="The run (its ID, or the start of it)."),
+    limit: int = typer.Option(50, "--limit", "-n", min=1, help="How many of the newest calls to show."),
+    tool: str = typer.Option(None, "--tool", help="Only this tool's calls."),
+) -> None:
+    """The calls a run made through a connection (newest last; no secrets).
+
+    Example: corethink connection calls orders-api --job 3f2a
+    """
+    name = _resolve(name)
+    job_id = _resolve_job(job)
+    data = client().get(_path(name, "/calls"), job=job_id) or {}
+    rows = [row for row in data.get("calls") or [] if not tool or row.get("tool") == tool]
+    shown = rows[-limit:]
+    status_style = {"ok": "green", "error": "yellow", "failed": "red", "dry_run": "cyan"}
+
+    def human() -> None:
+        ui.table(
+            shown,
+            [
+                ("When", lambda r: ui.when(r.get("at"))),
+                ("Tool", "tool"),
+                (
+                    "Status",
+                    lambda r: Text(
+                        str(r.get("status") or "—"),
+                        style=status_style.get(str(r.get("status")), ""),
+                    ),
+                ),
+                ("HTTP", "http_status"),
+                (
+                    "ms",
+                    lambda r: round(float(r["latency_ms"])) if r.get("latency_ms") is not None else None,
+                ),
+                (
+                    "Arguments",
+                    lambda r: _clip(r.get("args"), 70) if r.get("args") is not None else None,
+                ),
+            ],
+            empty="This run made no calls through it.",
+        )
+        total = int(data.get("total") or 0)
+        if total > len(shown):
+            more = " (the run kept its newest 500)" if data.get("truncated") else ""
+            ui.info(f"Showing {len(shown)} of {total} calls{more}. --limit shows more; --json shows each in full.")
+
+    ui.emit({**data, "calls": shown}, human)
+
+
+app.add_typer(secret_app, name="secret")
+
+
+def register(root: typer.Typer) -> None:
+    root.add_typer(app, name="connection", rich_help_panel="Build")