superqode 2.2.0__tar.gz → 2.2.1__tar.gz

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

@@ -7,6 +7,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.2.1] - 2026-09-12
+
+Local UHP for the package cut: SuperQode speaks it as a client (connect, run,
+file upload and artifact download) and as a native Core server that binds one
+HarnessSpec. Harness stop reasons map to UHP failed or incomplete instead of an
+empty completed response. The same cut includes A2ABreak card-review and
+contextId hardening. A public UHP host (GoDaddy) and Google Cloud infra stay for
+2.3.0.
+
+### 🧩 Unified Harness Protocol
+
+- Client path: `superqode connect uhp` discovers a server and selects a harness;
+  `harness run uhp` runs tasks through the same session, event and evidence model
+  as a local harness.
+- File upload and artifact download: `--file` / `input_files=` send local files
+  through `POST /v1/files`; `--download-dir` and `download_citations` write
+  `container_file_citation` artifacts back to disk.
+- Native server: `superqode serve uhp --spec harness.yaml` exposes one configured
+  HarnessSpec over UHP Core. Complementary to HarnessRouter (a multi-backend
+  runner), not a substitute for it.
+- Harness `stopped_reason` values such as `error`, `blocked` and `loop_detected`
+  map to UHP `failed`; `needs_approval` and `max_iterations` map to `incomplete`.
+  An empty provider failure is no longer reported as `completed`.
+- The server advertises `conformance_class: core`. That names the surface it
+  implements; it is not a UHP conformance-suite certificate.
+
+### 🔐 A2ABreak hardening
+
+- Card review on connect/inspect surfaces SuperOptiX-aligned findings, and
+  `contextId` plus task ACL bind to the caller principal (protocol gaps, not
+  product CVEs).
+
 ## [2.2.0] - 2026-09-07
 
 Every Harness Hub record now states the language its harness is implemented in,

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superqode
-Version: 2.2.0
+Version: 2.2.1
 Summary: The harness layer for coding agents
 Author-email: Shashi Jagtap <info@super-agentic.ai>
 Maintainer-email: Shashi Jagtap <info@super-agentic.ai>
@@ -439,6 +439,14 @@ can call it today:
 superqode connect a2a --url https://a2a.superqode.dev
 ```
 
+Or use the A2A project's official CLI ([`a2a`](https://github.com/a2aproject/a2a-cli)):
+
+```bash
+a2a card get -a https://a2a.superqode.dev
+a2a send -a https://a2a.superqode.dev \
+  "Which harness should we shortlist for a Python monorepo?"
+```
+
 It scores 100% of MUST and 100% of MAY against the
 [Technology Compatibility Kit](https://github.com/a2aproject/a2a-tck) the A2A
 project maintains under the Linux Foundation, on the JSON-RPC and HTTP+JSON
@@ -460,6 +468,23 @@ superqode a2a-keys issue "Acme Corp" --tier one-off --days 30
 
 Read the [A2A guide](docs/providers/a2a.md).
 
+## Serve a Harness Over UHP
+
+The same install that drives a remote UHP server can also expose a local
+HarnessSpec so other UHP clients call SuperQode:
+
+```bash
+superqode serve uhp --spec harness.yaml --port 8787
+superqode connect uhp --base-url http://127.0.0.1:8787
+superqode harness run uhp --prompt "summarise this repository"
+```
+
+`serve uhp` binds one HarnessSpec and advertises UHP Core. It is complementary
+to HarnessRouter, which wraps third-party CLIs as a catalog. Core names the
+surface SuperQode implements; it is not a conformance-suite certificate.
+
+Read the [UHP guide](docs/providers/uhp.md).
+
 ## Harness Execution Model
 
 ```text
@@ -495,11 +520,12 @@ superqode harness graph <run-id> --json
 
 | Guide | What it covers |
 | --- | --- |
-| [Website](https://superqode.dev) | Product, Hub, A2A agent |
+| [Website](https://superqode.dev) | Product, Hub, A2A and UHP |
 | [Quick Start](https://docs.superqode.dev/getting-started/quickstart/) | Install, connect, and run your first task |
 | [Harness Hub](https://docs.superqode.dev/harness-hub/) | Browsing, filtering, and the published catalog |
-| [Connection Methods](docs/concepts/modes.md) | Local, ACP, BYOK, SDK, MCP, and A2A routes |
+| [Connection Methods](docs/concepts/modes.md) | Local, ACP, BYOK, SDK, MCP, A2A, and UHP routes |
 | [A2A Agents](docs/providers/a2a.md) | Serving a harness over A2A, skills, API keys, and the Agent Card |
+| [UHP](docs/providers/uhp.md) | Client connect/run, file upload, and native `serve uhp` (Core class) |
 | [Developer Workflows](docs/developer-workflows.md) | The complete TUI and CLI command set |
 | [Harness System](docs/advanced/harness-system.md) | HarnessSpec fields, runtimes, and policy |
 | [Harness Protocol](docs/advanced/harness-protocol.md) | The versioned session and evidence contract |

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

@@ -288,6 +288,14 @@ can call it today:
 superqode connect a2a --url https://a2a.superqode.dev
 ```
 
+Or use the A2A project's official CLI ([`a2a`](https://github.com/a2aproject/a2a-cli)):
+
+```bash
+a2a card get -a https://a2a.superqode.dev
+a2a send -a https://a2a.superqode.dev \
+  "Which harness should we shortlist for a Python monorepo?"
+```
+
 It scores 100% of MUST and 100% of MAY against the
 [Technology Compatibility Kit](https://github.com/a2aproject/a2a-tck) the A2A
 project maintains under the Linux Foundation, on the JSON-RPC and HTTP+JSON
@@ -309,6 +317,23 @@ superqode a2a-keys issue "Acme Corp" --tier one-off --days 30
 
 Read the [A2A guide](docs/providers/a2a.md).
 
+## Serve a Harness Over UHP
+
+The same install that drives a remote UHP server can also expose a local
+HarnessSpec so other UHP clients call SuperQode:
+
+```bash
+superqode serve uhp --spec harness.yaml --port 8787
+superqode connect uhp --base-url http://127.0.0.1:8787
+superqode harness run uhp --prompt "summarise this repository"
+```
+
+`serve uhp` binds one HarnessSpec and advertises UHP Core. It is complementary
+to HarnessRouter, which wraps third-party CLIs as a catalog. Core names the
+surface SuperQode implements; it is not a conformance-suite certificate.
+
+Read the [UHP guide](docs/providers/uhp.md).
+
 ## Harness Execution Model
 
 ```text
@@ -344,11 +369,12 @@ superqode harness graph <run-id> --json
 
 | Guide | What it covers |
 | --- | --- |
-| [Website](https://superqode.dev) | Product, Hub, A2A agent |
+| [Website](https://superqode.dev) | Product, Hub, A2A and UHP |
 | [Quick Start](https://docs.superqode.dev/getting-started/quickstart/) | Install, connect, and run your first task |
 | [Harness Hub](https://docs.superqode.dev/harness-hub/) | Browsing, filtering, and the published catalog |
-| [Connection Methods](docs/concepts/modes.md) | Local, ACP, BYOK, SDK, MCP, and A2A routes |
+| [Connection Methods](docs/concepts/modes.md) | Local, ACP, BYOK, SDK, MCP, A2A, and UHP routes |
 | [A2A Agents](docs/providers/a2a.md) | Serving a harness over A2A, skills, API keys, and the Agent Card |
+| [UHP](docs/providers/uhp.md) | Client connect/run, file upload, and native `serve uhp` (Core class) |
 | [Developer Workflows](docs/developer-workflows.md) | The complete TUI and CLI command set |
 | [Harness System](docs/advanced/harness-system.md) | HarnessSpec fields, runtimes, and policy |
 | [Harness Protocol](docs/advanced/harness-protocol.md) | The versioned session and evidence contract |

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

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

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

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

{superqode-2.2.0 → superqode-2.2.1}/src/superqode/a2a/client.py

@@ -214,6 +214,7 @@ class A2AClient:
             fallback = self.agent_url
 
         self.inspect.auth(auth_summary(data))
+        self._record_card_review(data)
         selected, skipped = _select_interface(interfaces, fallback)
         listed = interfaces if isinstance(interfaces, list) else []
         note = ""
@@ -237,6 +238,36 @@ class A2AClient:
         )
         return card, binding, version
 
+    def _record_card_review(self, data: dict) -> None:
+        """Record A2ABreak card-review findings. Never treat JWS as auth."""
+        from superqode.a2a.trust import (
+            origin_is_allowed,
+            parse_origin_allowlist,
+            record_card_review,
+            resolve_jws_trust_root,
+            review_agent_card,
+        )
+
+        allowed = getattr(self, "allowed_origins", None)
+        if allowed is None:
+            allowed = parse_origin_allowlist()
+        trust_root = getattr(self, "jws_trust_root", None)
+        if trust_root is None:
+            trust_root = resolve_jws_trust_root()
+        review = review_agent_card(
+            data,
+            origin=self.agent_url,
+            allowed_origins=tuple(allowed or ()),
+            jws_trust_root=str(trust_root or ""),
+        )
+        self._card_review = review
+        record_card_review(self.inspect, review)
+        if tuple(allowed or ()) and not origin_is_allowed(self.agent_url, tuple(allowed)):
+            raise A2AClientError(
+                f"Origin is not on the A2A allowlist: {self.agent_url}",
+                inspect=self.inspect,
+            )
+
     async def _ensure_interface(self) -> tuple[str, str, str]:
         if self._interface_url is None or self._binding is None or self._protocol_version is None:
             await self.get_agent_card()

{superqode-2.2.0 → superqode-2.2.1}/src/superqode/a2a/conformance.py

@@ -84,6 +84,8 @@ async def run_a2a_conformance(
     send: bool = True,
     http_client=None,
     timeout: float = 180.0,
+    allowed_origins: tuple[str, ...] = (),
+    jws_trust_root: str = "",
 ) -> A2AConformanceReport:
     """Run the four checks against ``settings.url``."""
     from superqode.a2a.client import A2AClient, A2AClientError
@@ -105,6 +107,10 @@ async def run_a2a_conformance(
         client_key=settings.key or None,
         timeout=timeout,
     ) as client:
+        if allowed_origins:
+            client.allowed_origins = allowed_origins
+        if jws_trust_root:
+            client.jws_trust_root = jws_trust_root
         try:
             card = await client.get_agent_card()
         except A2AClientError as exc:

superqode-2.2.1/src/superqode/a2a/context.py

@@ -0,0 +1,132 @@
+"""Principal-bound A2A context ownership (A2ABreak).
+
+The A2A spec lets a client supply ``contextId`` and does not bind it to a
+caller. SuperQode binds each context to the caller principal (API key id,
+operator, opaque ``X-SuperQode-Caller-Key``, or per-caller anonymous
+isolation) and refuses cross-principal reuse.
+
+This is not the SuperOptiX cookie model. SuperQode already has API keys and
+an operator token. Anonymous callers can send an opaque caller key, otherwise
+they are isolated by the same address identity used for rate limits.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from superqode.a2a.keys import ANONYMOUS_TIER, OPERATOR_TIER
+from superqode.a2a.limits import caller_identity
+
+#: Opaque per-caller key for anonymous isolation. Not a SuperOptiX cookie.
+CALLER_HEADER = "x-superqode-caller-key"
+
+CONTEXT_OWNERSHIP_MESSAGE = (
+    "This contextId is bound to another caller. The A2A spec does not "
+    "assign context ownership; SuperQode binds each context to the "
+    "caller that created it."
+)
+
+
+class ContextOwnershipError(Exception):
+    """Client-supplied contextId belongs to a different principal."""
+
+    def __init__(self, context_id: str) -> None:
+        super().__init__(CONTEXT_OWNERSHIP_MESSAGE)
+        self.context_id = context_id
+
+
+class SuperQodeA2AUser:
+    """Caller principal presented to the official A2A task store.
+
+    ``user_name`` is the owner key the SDK uses for List, Get, Cancel, and
+    Subscribe. Anonymous callers still receive a non-empty name so they are
+    not collapsed into one shared bucket.
+    """
+
+    def __init__(self, name: str, *, authenticated: bool) -> None:
+        self._name = name
+        self._authenticated = authenticated
+
+    @property
+    def is_authenticated(self) -> bool:
+        return self._authenticated
+
+    @property
+    def user_name(self) -> str:
+        return self._name
+
+
+class ContextOwnerStore:
+    """In-process map of contextId to the principal that claimed it."""
+
+    def __init__(self) -> None:
+        self._owners: dict[str, str] = {}
+
+    def owner_of(self, context_id: str) -> str | None:
+        return self._owners.get(context_id)
+
+    def claim(
+        self,
+        context_id: str,
+        principal: str,
+        *,
+        stored_owner: str | None = None,
+    ) -> None:
+        """Bind ``context_id`` to ``principal``, or reject a cross-principal reuse."""
+        existing = self._owners.get(context_id) or (stored_owner or "").strip() or None
+        if existing:
+            self._owners[context_id] = existing
+            if existing != principal:
+                raise ContextOwnershipError(context_id)
+            return
+        self._owners[context_id] = principal
+
+
+def valid_caller_key(value: str) -> bool:
+    """Accept a short opaque token, the same shape SuperOptiX uses on the header."""
+    if not value or not (8 <= len(value) <= 128):
+        return False
+    return all(char.isalnum() or char in "-_" for char in value)
+
+
+def request_principal(decision: Any, request: Any) -> str:
+    """Resolve the principal for an HTTP request after access is decided."""
+    tier = str(getattr(decision, "tier", "") or ANONYMOUS_TIER)
+    key_id = str(getattr(decision, "key_id", "") or "")
+    if tier == OPERATOR_TIER:
+        return "operator"
+    if key_id:
+        return f"key:{key_id}"
+    header = ""
+    try:
+        header = (request.headers.get(CALLER_HEADER) or "").strip()
+    except AttributeError:
+        header = ""
+    if valid_caller_key(header):
+        return f"caller:{header}"
+    host = getattr(getattr(request, "client", None), "host", None)
+    try:
+        forwarded = request.headers.get("x-forwarded-for")
+    except AttributeError:
+        forwarded = None
+    return caller_identity("", host, forwarded)
+
+
+def caller_principal(context: Any) -> str:
+    """Return the principal recorded on an executor call context."""
+    call_context = getattr(context, "call_context", None)
+    state = getattr(call_context, "state", None) or {}
+    identity = str(state.get("identity") or "").strip()
+    if identity:
+        return identity
+    user = getattr(call_context, "user", None)
+    user_name = str(getattr(user, "user_name", "") or "").strip()
+    if user_name:
+        return user_name
+    key_id = str(state.get("key_id") or "").strip()
+    if key_id:
+        return f"key:{key_id}"
+    tier = str(state.get("tier") or ANONYMOUS_TIER)
+    if tier == OPERATOR_TIER:
+        return "operator"
+    return "anonymous:unknown"

{superqode-2.2.0 → superqode-2.2.1}/src/superqode/a2a/inspect.py

@@ -97,6 +97,10 @@ class InspectLog:
     def auth(self, summary: str, **detail: Any) -> None:
         self.add("auth", summary, **detail)
 
+    def trust(self, summary: str, **detail: Any) -> None:
+        """One Agent Card protocol-risk finding (A2ABreak)."""
+        self.add("trust", summary, **detail)
+
     def lines(self) -> list[str]:
         return [event.summary for event in self.events]
 

{superqode-2.2.0 → superqode-2.2.1}/src/superqode/a2a/server.py

@@ -22,8 +22,15 @@ if TYPE_CHECKING:
     from superqode.agent.loop import AgentConfig
     from superqode.harness import HarnessProtocolController, HarnessSessionRef, HarnessSpec
 
+from superqode.a2a.context import (
+    ContextOwnershipError,
+    ContextOwnerStore,
+    SuperQodeA2AUser,
+    caller_principal,
+    request_principal,
+)
 from superqode.a2a.keys import ANONYMOUS_TIER, AccessDecision, decide_access
-from superqode.a2a.limits import RateLimiter, RateLimitPolicy, caller_identity
+from superqode.a2a.limits import RateLimiter, RateLimitPolicy
 
 
 #: The version reported in the Agent Card.
@@ -121,7 +128,7 @@ class A2AServerConfig(BaseModel):
     #: Must resolve.  Host platforms render this in their agent gallery, and a
     #: dead URL shows as a broken image rather than as no image.
     #: ``scripts/check_published_agent_card.py`` verifies it.
-    icon_url: str = "https://super-agentic.ai/uploads/superqode.png"
+    icon_url: str = "https://superqode.dev/assets/superqode.png"
     jsonrpc_path: str = "/"
     #: Also advertise and serve the A2A 0.3 wire format.  Gemini Enterprise,
     #: Foundry Agent Service, and Agent Registry all still accept 0.3 cards,
@@ -197,6 +204,7 @@ class SuperQodeA2AExecutor:
         self.config = config
         self._sessions: dict[str, HarnessSessionRef] = {}
         self._task_sessions: dict[str, HarnessSessionRef] = {}
+        self._owners = ContextOwnerStore()
         self._session_lock = asyncio.Lock()
 
     async def execute(self, context: Any, event_queue: Any) -> None:
@@ -216,6 +224,17 @@ class SuperQodeA2AExecutor:
         await updater.start_work()
 
         user_input = context.get_user_input()
+        principal = caller_principal(context)
+        try:
+            self._owners.claim(
+                context_id,
+                principal,
+                stored_owner=self._stored_owner(context_id),
+            )
+        except ContextOwnershipError as exc:
+            await updater.failed(updater.new_agent_message([sdk["Part"](text=str(exc))]))
+            return
+
         if self._wants_shortlist(context, user_input):
             await self._answer_shortlist(
                 updater,
@@ -246,7 +265,11 @@ class SuperQodeA2AExecutor:
             )
             return
 
-        session = await self._session_for(context_id)
+        try:
+            session = await self._session_for(context_id, principal)
+        except ContextOwnershipError as exc:
+            await updater.failed(updater.new_agent_message([sdk["Part"](text=str(exc))]))
+            return
         self._task_sessions[task_id] = session
         artifact_id = f"superqode-{task_id}"
         content: list[str] = []
@@ -418,6 +441,10 @@ class SuperQodeA2AExecutor:
         sdk = _a2a_sdk()
         task_id = _required_id(context.task_id, "task")
         context_id = _required_id(context.context_id, "context")
+        principal = caller_principal(context)
+        owner = self._owners.owner_of(context_id) or self._stored_owner(context_id)
+        if owner and owner != principal:
+            return
         session = self._task_sessions.get(task_id)
         if session is not None:
             try:
@@ -428,7 +455,14 @@ class SuperQodeA2AExecutor:
                 pass
         await sdk["TaskUpdater"](event_queue, task_id, context_id).cancel()
 
-    async def _session_for(self, context_id: str) -> HarnessSessionRef:
+    def _stored_owner(self, context_id: str) -> str | None:
+        record = self.controller.store.get_session(f"a2a-{context_id}")
+        if record is None:
+            return None
+        owner = str((record.metadata or {}).get("a2a_owner") or "").strip()
+        return owner or None
+
+    async def _session_for(self, context_id: str, principal: str) -> HarnessSessionRef:
         from superqode.harness import HarnessCreateRequest
 
         async with self._session_lock:
@@ -437,7 +471,11 @@ class SuperQodeA2AExecutor:
                 return cached
 
             session_id = f"a2a-{context_id}"
-            if self.controller.store.get_session(session_id) is not None:
+            stored = self.controller.store.get_session(session_id)
+            if stored is not None:
+                stored_owner = str((stored.metadata or {}).get("a2a_owner") or "").strip()
+                if stored_owner and stored_owner != principal:
+                    raise ContextOwnershipError(context_id)
                 session = await self.controller.resume(session_id)
             else:
                 descriptor = self.controller.descriptors()[0]
@@ -448,7 +486,11 @@ class SuperQodeA2AExecutor:
                         model=self.config.model,
                         working_directory=self.config.working_directory.resolve(),
                         session_id=session_id,
-                        metadata={"transport": "a2a", "a2a_context_id": context_id},
+                        metadata={
+                            "transport": "a2a",
+                            "a2a_context_id": context_id,
+                            "a2a_owner": principal,
+                        },
                     )
                 )
             self._sessions[context_id] = session
@@ -600,11 +642,7 @@ class A2AServer:
                     content={"detail": f"Unauthorized: {decision.reason}"},
                     headers={"WWW-Authenticate": "Bearer"},
                 )
-            identity = caller_identity(
-                decision.key_id,
-                getattr(getattr(request, "client", None), "host", None),
-                request.headers.get("x-forwarded-for"),
-            )
+            identity = request_principal(decision, request)
             limit = limiter.check(identity, decision.tier)
             if not limit.allowed:
                 return sdk["JSONResponse"](
@@ -616,6 +654,7 @@ class A2AServer:
             # Carried on the scope so the call-context builder, and through it
             # the executor, can see which tier is asking.
             request.state.superqode_access = decision
+            request.state.superqode_identity = identity
             return await call_next(request)
 
         if self._task_engine is not None:
@@ -879,8 +918,17 @@ def _AccessContextBuilder(sdk: dict[str, Any]) -> Any:
         def build(self, request: Any) -> Any:
             context = super().build(request)
             decision = getattr(request.state, "superqode_access", None)
+            identity = str(getattr(request.state, "superqode_identity", "") or "").strip()
             if isinstance(decision, AccessDecision):
                 context.state.update(decision.to_state())
+            if not identity and isinstance(decision, AccessDecision):
+                identity = request_principal(decision, request)
+            if identity:
+                context.state["identity"] = identity
+                authenticated = bool(
+                    isinstance(decision, AccessDecision) and not decision.anonymous
+                )
+                context.user = SuperQodeA2AUser(identity, authenticated=authenticated)
             return context
 
     return _Builder()