superqode 2.2.1__tar.gz → 2.2.2__tar.gz

{superqode-2.2.1 → superqode-2.2.2}/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.2.2] - 2026-09-12
+
+The installed CLI can complete a harness turn against a BYOK UHP host such as
+`uhp.superqode.dev`. The client sends the caller's provider key
+(`GEMINI_API_KEY` / `GOOGLE_API_KEY` when the provider is Google). The public
+Core bind stays catalog-open and does not attach a model key. A separate Cloud
+Run image (`Dockerfile.uhp`) deploys that bind without touching A2A.
+
+### 🧩 Unified Harness Protocol
+
+- `UHPClient` and `harness run uhp` send `X-Provider-Api-Key` from the
+  caller's environment so a remote Core host can run a turn without a
+  server-side `GEMINI_API_KEY`.
+- Remote `serve uhp --allow-remote` requires `--api-key`. Catalog GETs stay
+  public; `POST /v1/responses` without the caller provider key returns
+  `missing_provider_key` and does not start LiteLLM.
+- Public bind defaults: provider `google`, model `gemini-flash-latest`, harness
+  `chrn_superqode_core`. Image and Cloud Build files are `Dockerfile.uhp` and
+  `cloudbuild.uhp.yaml` (service `superqode-uhp`).
+
 ## [2.2.1] - 2026-09-12
 
 Local UHP for the package cut: SuperQode speaks it as a client (connect, run,

{superqode-2.2.1 → superqode-2.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superqode
-Version: 2.2.1
+Version: 2.2.2
 Summary: The harness layer for coding agents
 Author-email: Shashi Jagtap <info@super-agentic.ai>
 Maintainer-email: Shashi Jagtap <info@super-agentic.ai>
@@ -483,6 +483,12 @@ superqode harness run uhp --prompt "summarise this repository"
 to HarnessRouter, which wraps third-party CLIs as a catalog. Core names the
 surface SuperQode implements; it is not a conformance-suite certificate.
 
+The public hostname for that bind is [`uhp.superqode.dev`](https://uhp.superqode.dev/v1/uhp).
+Anonymous callers get discovery and the static harness catalog (no model call).
+A harness turn requires a SuperQode UHP API key and the caller's own provider
+key. SuperQode does not pay for that model. Until the hostname is mapped, use
+local `serve uhp` as above.
+
 Read the [UHP guide](docs/providers/uhp.md).
 
 ## Harness Execution Model

{superqode-2.2.1 → superqode-2.2.2}/README.md

@@ -332,6 +332,12 @@ superqode harness run uhp --prompt "summarise this repository"
 to HarnessRouter, which wraps third-party CLIs as a catalog. Core names the
 surface SuperQode implements; it is not a conformance-suite certificate.
 
+The public hostname for that bind is [`uhp.superqode.dev`](https://uhp.superqode.dev/v1/uhp).
+Anonymous callers get discovery and the static harness catalog (no model call).
+A harness turn requires a SuperQode UHP API key and the caller's own provider
+key. SuperQode does not pay for that model. Until the hostname is mapped, use
+local `serve uhp` as above.
+
 Read the [UHP guide](docs/providers/uhp.md).
 
 ## Harness Execution Model

{superqode-2.2.1 → superqode-2.2.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "superqode"
-version = "2.2.1"
+version = "2.2.2"
 description = "The harness layer for coding agents"
 readme = "README.md"
 license = "Apache-2.0"

{superqode-2.2.1 → superqode-2.2.2}/src/superqode/__init__.py

@@ -38,7 +38,7 @@ __all__ = [
     "sidebar",
 ]
 
-__version__ = "2.2.1"
+__version__ = "2.2.2"
 
 # Stable, lightweight public extension surface.  Importing this package does
 # not discover or execute third-party extensions; discovery happens only when

{superqode-2.2.1 → superqode-2.2.2}/src/superqode/commands/serve.py

@@ -351,7 +351,7 @@ def serve_a2a(
     "--api-key",
     envvar="SUPERQODE_UHP_API_KEY",
     default=None,
-    help="Optional bearer token; when set, all routes except discovery require it",
+    help="Bearer token. Required with --allow-remote. Catalog GETs stay public.",
 )
 @click.option("--allow-remote", is_flag=True, help="Allow binding outside localhost")
 @click.option(
@@ -380,10 +380,11 @@ def serve_uhp(
     is_loopback = host in {"127.0.0.1", "localhost", "::1"}
     if not is_loopback and not allow_remote:
         raise click.ClickException("Use --allow-remote to bind outside localhost.")
-    if allow_remote and not api_key:
-        console.print(
-            "[yellow]Remote UHP bind without --api-key / SUPERQODE_UHP_API_KEY; "
-            "discovery is public and every other route is open.[/yellow]"
+    if allow_remote and not (api_key or "").strip():
+        raise click.ClickException(
+            "Remote UHP bind requires --api-key / SUPERQODE_UHP_API_KEY. "
+            "Catalog GETs stay public; harness turns need the bearer and "
+            "the caller's X-Provider-Api-Key."
         )
 
     server = create_uhp_server(
@@ -393,6 +394,8 @@ def serve_uhp(
         working_directory=working_dir.resolve(),
         api_key=api_key,
         harness_id=harness_id,
+        public_catalog=allow_remote,
+        require_caller_provider_key=allow_remote,
     )
     console.print(
         f"[cyan]Serving SuperQode UHP {server.discovery_document()['default_version']} "

{superqode-2.2.1 → superqode-2.2.2}/src/superqode/harness/uhp_client.py

@@ -14,6 +14,7 @@ from __future__ import annotations
 import base64
 import json
 import mimetypes
+import os
 import uuid
 from collections.abc import AsyncIterator, Mapping, Sequence
 from dataclasses import dataclass, field
@@ -32,6 +33,18 @@ VERSION_HEADER = "UHP-Version"
 #: workspace, so every task submission carries one.
 IDEMPOTENCY_HEADER = "Idempotency-Key"
 
+#: Caller model key for a BYOK UHP server. SuperQode does not send its own.
+PROVIDER_KEY_HEADER = "X-Provider-Api-Key"
+
+
+def _caller_provider_api_key() -> str:
+    """Return the caller's model key for a BYOK UHP server, if present."""
+    provider = (os.environ.get("SUPERQODE_PROVIDER") or "google").strip() or "google"
+    if provider in {"google", "gemini"}:
+        return (os.environ.get("GEMINI_API_KEY") or os.environ.get("GOOGLE_API_KEY") or "").strip()
+    return (os.environ.get(f"{provider.upper()}_API_KEY") or "").strip()
+
+
 _TERMINAL_STREAM_EVENTS = frozenset(
     {
         "response.completed",
@@ -505,6 +518,9 @@ class UHPClient:
         }
         if api_key:
             self._headers["Authorization"] = f"Bearer {api_key}"
+        provider_key = _caller_provider_api_key()
+        if provider_key and PROVIDER_KEY_HEADER not in self._headers:
+            self._headers[PROVIDER_KEY_HEADER] = provider_key
         self._client = client
         self._owns_client = client is None
 

{superqode-2.2.1 → superqode-2.2.2}/src/superqode/harness/uhp_server.py

@@ -14,6 +14,7 @@ from __future__ import annotations
 
 import asyncio
 import json
+import os
 import re
 import time
 import uuid
@@ -27,7 +28,11 @@ try:
 except Exception:  # pragma: no cover - optional at import time
     FastAPIRequest = Any  # type: ignore[misc,assignment]
 
-from superqode.harness.uhp_client import UHP_PROTOCOL_VERSION, VERSION_HEADER
+from superqode.harness.uhp_client import (
+    PROVIDER_KEY_HEADER,
+    UHP_PROTOCOL_VERSION,
+    VERSION_HEADER,
+)
 
 #: Advertised and accepted protocol version.
 SUPPORTED_VERSION = UHP_PROTOCOL_VERSION
@@ -158,6 +163,10 @@ class UHPServerConfig:
     implementation_version: str = ""
     #: Honest claim: core endpoints only; suite not yet run.
     conformance_class: str = "core"
+    #: GET catalog without a bearer (remote public host). POST still requires api_key.
+    public_catalog: bool = False
+    #: Refuse a harness turn unless the caller sent PROVIDER_KEY_HEADER.
+    require_caller_provider_key: bool = False
 
 
 def _package_version() -> str:
@@ -169,6 +178,20 @@ def _package_version() -> str:
         return "0.0.0"
 
 
+def _provider_key_env(provider: str) -> str:
+    """Env var LiteLLM reads for this provider (caller BYOK)."""
+    try:
+        from superqode.providers.registry import PROVIDERS
+
+        pdef = PROVIDERS.get(provider)
+        names = getattr(pdef, "env_vars", None) or ()
+        if names:
+            return str(names[0])
+    except Exception:
+        pass
+    return f"{(provider or 'OPENAI').upper()}_API_KEY"
+
+
 def harness_id_from_name(name: str) -> str:
     """Build a ``chrn_…`` id from a harness/spec name."""
     slug = re.sub(r"[^a-z0-9]+", "_", (name or "superqode").lower()).strip("_")
@@ -369,8 +392,8 @@ class UHPServer:
                     content=negotiated,
                     headers={VERSION_HEADER: SUPPORTED_VERSION},
                 )
-            # Discovery is unauthenticated per the OpenAPI contract.
-            if not server._is_public_path(request.url.path):
+            # Discovery (and optional catalog GETs) stay unauthenticated.
+            if not server._is_public_request(request.method, request.url.path):
                 auth_error = server._check_auth(request.headers.get("authorization"))
                 if auth_error is not None:
                     return JSONResponse(
@@ -504,8 +527,27 @@ class UHPServer:
                 status, envelope = harness_error
                 return JSONResponse(status_code=status, content=envelope)
 
+            provider_api_key = (http_request.headers.get(PROVIDER_KEY_HEADER) or "").strip()
+            if server.config.require_caller_provider_key and not provider_api_key:
+                return JSONResponse(
+                    status_code=403,
+                    content=_error_envelope(
+                        error_type="permission_error",
+                        code="missing_provider_key",
+                        message=(
+                            f"Harness turns on this host require header '{PROVIDER_KEY_HEADER}' "
+                            "(your provider key). SuperQode does not attach a model key."
+                        ),
+                        param=PROVIDER_KEY_HEADER,
+                    ),
+                )
+
             stream = bool(body.get("stream"))
-            started = await server._start_response(body, idempotency_key=idempotency_key or None)
+            started = await server._start_response(
+                body,
+                idempotency_key=idempotency_key or None,
+                provider_api_key=provider_api_key or None,
+            )
             if isinstance(started, tuple):
                 status, envelope = started
                 return JSONResponse(status_code=status, content=envelope)
@@ -620,9 +662,18 @@ class UHPServer:
 
     # -- auth / version ---------------------------------------------------------
 
-    @staticmethod
-    def _is_public_path(path: str) -> bool:
-        return path in {"/v1/uhp", "/health", "/docs", "/openapi.json", "/redoc"}
+    def _is_public_request(self, method: str, path: str) -> bool:
+        path = path.rstrip("/") or "/"
+        if path in {"/v1/uhp", "/health", "/docs", "/openapi.json", "/redoc"}:
+            return True
+        if not self.config.public_catalog or method.upper() != "GET":
+            return False
+        if path in {"/v1/harnesses", "/v1/models"}:
+            return True
+        if path.startswith("/v1/harnesses/"):
+            rest = path[len("/v1/harnesses/") :]
+            return "/" not in rest or rest.endswith("/models")
+        return False
 
     def _negotiate_version(self, requested: str | None) -> dict[str, Any] | None:
         if not requested or not requested.strip():
@@ -684,7 +735,11 @@ class UHPServer:
     # -- response lifecycle -----------------------------------------------------
 
     async def _start_response(
-        self, body: Mapping[str, Any], *, idempotency_key: str | None
+        self,
+        body: Mapping[str, Any],
+        *,
+        idempotency_key: str | None,
+        provider_api_key: str | None = None,
     ) -> dict[str, Any]:
         prompt = _extract_prompt(body.get("input"))
         previous_response_id = body.get("previous_response_id")
@@ -773,6 +828,7 @@ class UHPServer:
             metadata={
                 "harness_id": self.config.harness_id,
                 **(dict(body["metadata"]) if isinstance(body.get("metadata"), Mapping) else {}),
+                **({"provider_api_key": provider_api_key} if provider_api_key else {}),
             },
         )
 
@@ -979,13 +1035,21 @@ class UHPServer:
         if request.instructions:
             prompt = f"{request.instructions.rstrip()}\n\n{prompt}"
 
+        run_metadata = {
+            key: value for key, value in dict(request.metadata).items() if key != "provider_api_key"
+        }
+        token = str(request.metadata.get("provider_api_key") or "")
+        env_name = _provider_key_env(provider)
+        previous = os.environ.get(env_name)
+        if token:
+            os.environ[env_name] = token
         try:
             result = await session.prompt(
                 prompt,
                 provider=provider,
                 model=model,
                 working_directory=request.working_directory,
-                metadata=dict(request.metadata),
+                metadata=run_metadata,
             )
         except Exception:
             return UHPRunResult(
@@ -995,6 +1059,12 @@ class UHPServer:
                 error_code="harness_error",
                 usage=None,
             )
+        finally:
+            if token:
+                if previous is None:
+                    os.environ.pop(env_name, None)
+                else:
+                    os.environ[env_name] = previous
 
         if request.cancel_event and request.cancel_event.is_set():
             return UHPRunResult(
@@ -1015,6 +1085,8 @@ def create_uhp_server(
     harness_id: str | None = None,
     harness_name: str | None = None,
     runner: HarnessRunner | None = None,
+    public_catalog: bool = False,
+    require_caller_provider_key: bool = False,
 ) -> UHPServer:
     """Build a UHP server bound to one SuperQode HarnessSpec."""
     from superqode.harness import get_harness_template, load_harness_spec
@@ -1047,5 +1119,7 @@ def create_uhp_server(
         api_key=api_key,
         implementation_version=_package_version(),
         conformance_class="core",
+        public_catalog=public_catalog,
+        require_caller_provider_key=require_caller_provider_key,
     )
     return UHPServer(config, runner=runner, spec=loaded)

{superqode-2.2.1 → superqode-2.2.2}/src/superqode.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superqode
-Version: 2.2.1
+Version: 2.2.2
 Summary: The harness layer for coding agents
 Author-email: Shashi Jagtap <info@super-agentic.ai>
 Maintainer-email: Shashi Jagtap <info@super-agentic.ai>
@@ -483,6 +483,12 @@ superqode harness run uhp --prompt "summarise this repository"
 to HarnessRouter, which wraps third-party CLIs as a catalog. Core names the
 surface SuperQode implements; it is not a conformance-suite certificate.
 
+The public hostname for that bind is [`uhp.superqode.dev`](https://uhp.superqode.dev/v1/uhp).
+Anonymous callers get discovery and the static harness catalog (no model call).
+A harness turn requires a SuperQode UHP API key and the caller's own provider
+key. SuperQode does not pay for that model. Until the hostname is mapped, use
+local `serve uhp` as above.
+
 Read the [UHP guide](docs/providers/uhp.md).
 
 ## Harness Execution Model

{superqode-2.2.1 → superqode-2.2.2}/tests/test_uhp_server.py

@@ -12,7 +12,11 @@ from click.testing import CliRunner
 pytest.importorskip("fastapi", reason="UHP server tests require FastAPI")
 
 from superqode.commands.serve import serve
-from superqode.harness.uhp_client import UHP_PROTOCOL_VERSION, VERSION_HEADER
+from superqode.harness.uhp_client import (
+    PROVIDER_KEY_HEADER,
+    UHP_PROTOCOL_VERSION,
+    VERSION_HEADER,
+)
 from superqode.harness.uhp_server import (
     UHPRunRequest,
     UHPRunResult,
@@ -223,6 +227,49 @@ async def test_auth_and_version_negotiation():
         assert err["detail"]["supported"] == [UHP_PROTOCOL_VERSION]
 
 
+@pytest.mark.anyio
+async def test_public_catalog_and_byok_on_remote_bind():
+    server = _server(api_key="secret")
+    server.config.public_catalog = True
+    server.config.require_caller_provider_key = True
+    transport = httpx.ASGITransport(app=server.app)
+    async with httpx.AsyncClient(transport=transport, base_url="http://test") as client:
+        assert (await client.get("/v1/harnesses")).status_code == 200
+        assert (await client.get("/v1/models")).status_code == 200
+
+        denied = await client.post(
+            "/v1/responses",
+            headers={VERSION_HEADER: UHP_PROTOCOL_VERSION, "Idempotency-Key": "no-auth"},
+            json={"input": "hi"},
+        )
+        assert denied.status_code == 401
+
+        missing_provider = await client.post(
+            "/v1/responses",
+            headers={
+                VERSION_HEADER: UHP_PROTOCOL_VERSION,
+                "Idempotency-Key": "no-prov",
+                "Authorization": "Bearer secret",
+            },
+            json={"input": "hi"},
+        )
+        assert missing_provider.status_code == 403
+        assert missing_provider.json()["error"]["code"] == "missing_provider_key"
+
+        ok = await client.post(
+            "/v1/responses",
+            headers={
+                VERSION_HEADER: UHP_PROTOCOL_VERSION,
+                "Idempotency-Key": "with-prov",
+                "Authorization": "Bearer secret",
+                PROVIDER_KEY_HEADER: "sk-caller",
+            },
+            json={"input": "hi"},
+        )
+        assert ok.status_code == 200
+        assert ok.json()["status"] == "completed"
+
+
 @pytest.mark.anyio
 async def test_unknown_harness_on_create():
     server = _server()
@@ -255,6 +302,10 @@ def test_create_uhp_server_uses_template_and_cli_help():
     assert "--api-key" in result.output
     assert "UHP" in result.output
 
+    denied = runner.invoke(serve, ["uhp", "--host", "0.0.0.0", "--allow-remote"])
+    assert denied.exit_code != 0
+    assert "api-key" in denied.output.lower()
+
 
 @pytest.mark.anyio
 async def test_cancel_in_progress():