superqode 2.2.5__tar.gz → 2.3.0__tar.gz

{superqode-2.2.5 → superqode-2.3.0}/CHANGELOG.md

@@ -7,6 +7,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.3.0] - 2026-09-13
+
+The UHP server release. `serve uhp` serves session listing, inspection and
+turn history, so a client can find a session it did not record and rebuild its
+transcript. Core conformance stays at 40 of 40 with no skips.
+
+### 🧩 Unified Harness Protocol
+
+- **Sessions are inspectable.** `GET /v1/sessions` lists them newest first,
+  with cursor pagination that states the end of the listing instead of leaving
+  a client to infer it from a short page. `GET /v1/sessions/{id}` returns one,
+  and `GET /v1/sessions/{id}/turns` returns its ordered task history, each
+  turn carrying its response id, status, prompt and answer.
+- **Session listing is off on a shared bind.** The capability follows whether
+  the bind takes a caller-supplied provider key. One bearer shared by every
+  caller means a session list would hand each of them the others' prompts and
+  answers, so the public bind reports `session_listing: false` and answers
+  404, which is what a Core server does. A local bind reports it true.
+- Resuming a UHP session against a Core server no longer fails with an opaque
+  transport error. Turn history is an Extended surface, so a Core server
+  answering 404 there is correct and means there is no history to read. The
+  client now says the route cannot resume that session instead of reporting a
+  server failure.
+
 ## [2.2.5] - 2026-09-13
 
 SuperQode's UHP server adopts protocol `2026-09-12` and passes the UHP

{superqode-2.2.5 → superqode-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superqode
-Version: 2.2.5
+Version: 2.3.0
 Summary: The harness layer for coding agents
 Author-email: Shashi Jagtap <info@super-agentic.ai>
 Maintainer-email: Shashi Jagtap <info@super-agentic.ai>

{superqode-2.2.5 → superqode-2.3.0}/pyproject.toml

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

{superqode-2.2.5 → superqode-2.3.0}/src/superqode/__init__.py

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

{superqode-2.2.5 → superqode-2.3.0}/src/superqode/harness/uhp_client.py

@@ -991,8 +991,16 @@ class UHPClient:
         return tuple(dict(item) for item in _items(payload, "turns") if isinstance(item, Mapping))
 
     async def latest_response_id(self, session_id: str) -> str | None:
-        """Return the most recent response id recorded for a session."""
-        turns = await self.list_session_turns(session_id)
+        """Return the most recent response id recorded for a session.
+
+        Turn history is Extended: a Core server answers 404, meaning none.
+        """
+        try:
+            turns = await self.list_session_turns(session_id)
+        except UHPError as exc:
+            if exc.status_code == 404:
+                return None
+            raise
         for turn in reversed(turns):
             for key in ("response_id", "id"):
                 value = turn.get(key)

{superqode-2.2.5 → superqode-2.3.0}/src/superqode/harness/uhp_server.py

@@ -5,9 +5,9 @@ a *native* UHP server (Path A), complementary to HarnessRouter: SuperQode's own
 harness bind speaks the wire format directly, rather than wrapping Codex/Claude
 as a multi-backend runner.
 
-Targets UHP version ``2026-08-11``. Claims conformance class ``core`` honestly —
-the suite has not been run against this process, and Extended surfaces (files,
-session listing) are deferred.
+Serves UHP ``2026-09-12`` and ``2026-08-11``. Passes the conformance suite at
+class ``core``. Session listing is served where the bind is not shared; file
+artifacts are not implemented, so the class stays ``core``.
 """
 
 from __future__ import annotations
@@ -186,7 +186,7 @@ class UHPServerConfig:
     api_key: str | None = None
     implementation_name: str = "superqode"
     implementation_version: str = ""
-    #: Honest claim: core endpoints only; suite not yet run.
+    #: Backed by a suite run, which is the only claim the spec recognises.
     conformance_class: str = "core"
     #: GET catalog without a bearer (remote public host). POST still requires api_key.
     public_catalog: bool = False
@@ -195,6 +195,9 @@ class UHPServerConfig:
     #: Per-session directory under working_directory, so callers on a shared
     #: bind cannot read each other's files. Off locally: work in the project.
     isolate_session_workspaces: bool = False
+    #: Serve session listing. Off on a shared bind: one bearer for every
+    #: caller would make a list everyone's prompts.
+    expose_session_listing: bool = True
 
 
 def _package_version() -> str:
@@ -422,7 +425,7 @@ class UHPServer:
                 "cancellation": True,
                 "files_input": False,
                 "files_output": False,
-                "session_listing": False,
+                "session_listing": self.config.expose_session_listing,
                 "harness_management": False,
                 "session_sharing": False,
                 "idempotency": True,
@@ -729,6 +732,87 @@ class UHPServer:
             server._input_items.pop(response_id, None)
             return {"id": response_id, "deleted": True}
 
+        def _listing_disabled() -> Any:
+            return JSONResponse(
+                status_code=404,
+                content=_error_envelope(
+                    error_type="invalid_request_error",
+                    code="session_not_found",
+                    message="This bind does not serve session listing.",
+                ),
+            )
+
+        @app.get("/v1/sessions")
+        async def list_sessions(limit: str = "20", cursor: str = "", harness: str = "") -> Any:
+            # A string, so a bad value answers in the UHP error envelope.
+            if not server.config.expose_session_listing:
+                return _listing_disabled()
+            try:
+                requested = int(limit)
+            except (TypeError, ValueError):
+                return JSONResponse(
+                    status_code=400,
+                    content=_error_envelope(
+                        error_type="invalid_request_error",
+                        code="invalid_input",
+                        # Truncated: it is echoed back to the caller.
+                        message=f"Query parameter 'limit' must be an integer, got '{limit[:32]}'.",
+                        param="limit",
+                    ),
+                )
+            ordered = sorted(
+                server._sessions.values(),
+                key=lambda item: (-int(item.get("updated_at") or 0), str(item.get("id") or "")),
+            )
+            if harness:
+                ordered = [s for s in ordered if str(s.get("harness_id") or "") == harness]
+            start = 0
+            if cursor:
+                ids = [str(s.get("id") or "") for s in ordered]
+                start = ids.index(cursor) + 1 if cursor in ids else len(ordered)
+            size = max(1, min(requested, 100))
+            page = ordered[start : start + size]
+            # Explicit end marker: a short page does not mean the last one.
+            remaining = ordered[start + size :]
+            return {
+                "sessions": [server._session_document(item) for item in page],
+                "next_cursor": (str(page[-1].get("id")) if page and remaining else None),
+            }
+
+        @app.get("/v1/sessions/{session_id}")
+        async def get_session(session_id: str) -> Any:
+            if not server.config.expose_session_listing:
+                return _listing_disabled()
+            session = server._sessions.get(session_id)
+            if session is None:
+                return JSONResponse(
+                    status_code=404,
+                    content=_error_envelope(
+                        error_type="invalid_request_error",
+                        code="session_not_found",
+                        message=f"No session with id '{session_id}'.",
+                        param="session_id",
+                    ),
+                )
+            return server._session_document(session)
+
+        @app.get("/v1/sessions/{session_id}/turns")
+        async def get_session_turns(session_id: str) -> Any:
+            if not server.config.expose_session_listing:
+                return _listing_disabled()
+            session = server._sessions.get(session_id)
+            if session is None:
+                return JSONResponse(
+                    status_code=404,
+                    content=_error_envelope(
+                        error_type="invalid_request_error",
+                        code="session_not_found",
+                        message=f"No session with id '{session_id}'.",
+                        param="session_id",
+                    ),
+                )
+            return {"object": "list", "turns": server._session_turns(session)}
+
         @app.post("/v1/sessions/{session_id}/cancel")
         async def cancel_session(session_id: str) -> Any:
             session = server._sessions.get(session_id)
@@ -816,6 +900,54 @@ class UHPServer:
             )
         return None
 
+    def _output_text(self, record: Mapping[str, Any]) -> str:
+        """The assistant text of one response, in output order."""
+        parts: list[str] = []
+        for item in record.get("output") or ():
+            if not isinstance(item, Mapping):
+                continue
+            content = item.get("content")
+            if not isinstance(content, Sequence):
+                continue
+            for part in content:
+                if isinstance(part, Mapping) and part.get("type") == "output_text":
+                    parts.append(str(part.get("text") or ""))
+        return "".join(parts)
+
+    def _session_document(self, session: Mapping[str, Any]) -> dict[str, Any]:
+        response_ids = list(session.get("response_ids") or ())
+        latest = self._responses.get(response_ids[-1]) if response_ids else None
+        created_at = int(session.get("created_at") or 0)
+        return {
+            "id": str(session.get("id") or ""),
+            "object": "session",
+            "harness_id": str(session.get("harness_id") or self.config.harness_id),
+            "title": str(session.get("title") or ""),
+            "status": str((latest or {}).get("status") or "in_progress"),
+            "created_at": created_at,
+            "updated_at": int(session.get("updated_at") or created_at),
+        }
+
+    def _session_turns(self, session: Mapping[str, Any]) -> list[dict[str, Any]]:
+        """The ordered task history, so a client can rebuild a transcript."""
+        turns: list[dict[str, Any]] = []
+        for response_id in session.get("response_ids") or ():
+            record = self._responses.get(response_id)
+            if record is None:
+                continue
+            turn: dict[str, Any] = {
+                "id": response_id,
+                "status": str(record.get("status") or ""),
+            }
+            user = _extract_prompt(self._input_items.get(response_id))
+            if user:
+                turn["user"] = user
+            assistant = self._output_text(record)
+            if assistant:
+                turn["assistant"] = assistant
+            turns.append(turn)
+        return turns
+
     def _workspace_for(self, session_id: str) -> Path:
         """The directory a turn runs in."""
         root = Path(self.config.working_directory)
@@ -943,9 +1075,16 @@ class UHPServer:
         self._cancel_events[response_id] = asyncio.Event()
         session = self._sessions.setdefault(
             session_id,
-            {"id": session_id, "harness_id": self.config.harness_id, "response_ids": []},
+            {
+                "id": session_id,
+                "harness_id": self.config.harness_id,
+                "response_ids": [],
+                "created_at": created_at,
+                "title": prompt.strip().splitlines()[0][:80] if prompt.strip() else "",
+            },
         )
         session["response_ids"].append(response_id)
+        session["updated_at"] = created_at
         if idempotency_key:
             self._idempotency[idempotency_key] = response_id
 
@@ -1263,10 +1402,13 @@ def create_uhp_server(
     public_catalog: bool = False,
     require_caller_provider_key: bool = False,
     isolate_session_workspaces: bool | None = None,
+    expose_session_listing: bool | None = None,
 ) -> UHPServer:
     """Build a UHP server bound to one SuperQode HarnessSpec.
 
-    ``isolate_session_workspaces`` defaults to whether the bind is BYOK.
+    ``isolate_session_workspaces`` defaults to whether the bind is BYOK, and
+    ``expose_session_listing`` to the opposite: one bearer shared by every
+    caller makes a session list everyone's prompts.
     """
     from superqode.harness import get_harness_template, load_harness_spec
 
@@ -1305,5 +1447,10 @@ def create_uhp_server(
             if isolate_session_workspaces is None
             else isolate_session_workspaces
         ),
+        expose_session_listing=(
+            not require_caller_provider_key
+            if expose_session_listing is None
+            else expose_session_listing
+        ),
     )
     return UHPServer(config, runner=runner, spec=loaded)

{superqode-2.2.5 → superqode-2.3.0}/src/superqode.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: superqode
-Version: 2.2.5
+Version: 2.3.0
 Summary: The harness layer for coding agents
 Author-email: Shashi Jagtap <info@super-agentic.ai>
 Maintainer-email: Shashi Jagtap <info@super-agentic.ai>

{superqode-2.2.5 → superqode-2.3.0}/tests/test_uhp_client.py

@@ -1425,3 +1425,36 @@ def test_best_common_version_prefers_the_newest():
     alien = UHPDiscovery.from_payload({"versions": ["2019-01-01"]})
     assert alien.best_common_version == ""
     assert alien.speaks_target_version is False
+
+
+@pytest.mark.asyncio
+async def test_latest_response_id_tolerates_a_core_server():
+    """Turn history is Extended. A Core server 404s it and is still correct."""
+
+    def handler(request):
+        return httpx.Response(
+            404,
+            json={
+                "error": {
+                    "type": "invalid_request_error",
+                    "code": "session_not_found",
+                    "message": "No such route.",
+                }
+            },
+        )
+
+    async with _client(handler) as client:
+        assert await client.latest_response_id("hsess1") is None
+
+
+@pytest.mark.asyncio
+async def test_latest_response_id_still_raises_on_a_real_failure():
+    def handler(request):
+        return httpx.Response(
+            500,
+            json={"error": {"type": "server_error", "code": "boom", "message": "broke"}},
+        )
+
+    async with _client(handler) as client:
+        with pytest.raises(UHPError):
+            await client.latest_response_id("hsess1")

{superqode-2.2.5 → superqode-2.3.0}/tests/test_uhp_server.py

@@ -917,3 +917,117 @@ async def test_a_waiting_caller_gets_the_cancelled_record_not_an_error():
 
     assert blocked.status_code == 200
     assert blocked.json()["status"] == "cancelled"
+
+
+# ── session listing, inspection and turns ──────────────────────────────────────
+
+
+@pytest.mark.anyio
+async def test_sessions_can_be_listed_inspected_and_replayed():
+    server = _server()
+    transport = httpx.ASGITransport(app=server.app)
+    async with httpx.AsyncClient(transport=transport, base_url="http://test") as client:
+        first = (
+            await client.post(
+                "/v1/responses",
+                headers={VERSION_HEADER: UHP_PROTOCOL_VERSION, "Idempotency-Key": "s-1"},
+                json={"input": "summarise the readme"},
+            )
+        ).json()
+        session_id = first["metadata"]["session_id"]
+        await client.post(
+            "/v1/responses",
+            headers={VERSION_HEADER: UHP_PROTOCOL_VERSION, "Idempotency-Key": "s-2"},
+            json={"input": "now the changelog", "previous_response_id": first["id"]},
+        )
+
+        listing = await client.get("/v1/sessions?limit=5")
+        assert listing.status_code == 200
+        body = listing.json()
+        assert "next_cursor" in body, "no explicit end-of-pagination marker"
+        assert body["next_cursor"] is None
+        entry = next(s for s in body["sessions"] if s["id"] == session_id)
+        assert entry["object"] == "session"
+        assert entry["harness_id"] == "chrn_superqode"
+        assert entry["title"] == "summarise the readme"
+        assert entry["status"] == "completed"
+        assert entry["created_at"] and entry["updated_at"]
+
+        one = await client.get(f"/v1/sessions/{session_id}")
+        assert one.status_code == 200
+        assert one.json()["id"] == session_id
+
+        turns = await client.get(f"/v1/sessions/{session_id}/turns")
+        assert turns.status_code == 200
+        items = turns.json()["turns"]
+        assert len(items) == 2, "both turns of the session should be listed, in order"
+        for turn in items:
+            assert turn["id"].startswith("resp_")
+            assert turn["status"] == "completed"
+        assert items[0]["user"] == "summarise the readme"
+        assert items[0]["assistant"] == "echo:summarise the readme"
+        assert items[1]["user"] == "now the changelog"
+
+        missing = await client.get("/v1/sessions/hsessnope")
+        assert missing.status_code == 404
+        assert missing.json()["error"]["code"] == "session_not_found"
+
+
+@pytest.mark.anyio
+async def test_session_listing_pages_with_an_explicit_cursor():
+    server = _server()
+    transport = httpx.ASGITransport(app=server.app)
+    async with httpx.AsyncClient(transport=transport, base_url="http://test") as client:
+        for index in range(3):
+            await client.post(
+                "/v1/responses",
+                headers={VERSION_HEADER: UHP_PROTOCOL_VERSION, "Idempotency-Key": f"p-{index}"},
+                json={"input": f"task {index}"},
+            )
+
+        page = (await client.get("/v1/sessions?limit=2")).json()
+        assert len(page["sessions"]) == 2
+        # A full page that is not the last one must say so.
+        assert page["next_cursor"] is not None
+
+        rest = (await client.get(f"/v1/sessions?limit=2&cursor={page['next_cursor']}")).json()
+        assert len(rest["sessions"]) == 1
+        assert rest["next_cursor"] is None
+
+        seen = [s["id"] for s in page["sessions"]] + [s["id"] for s in rest["sessions"]]
+        assert len(set(seen)) == 3, "paging repeated or dropped a session"
+
+
+@pytest.mark.anyio
+async def test_session_listing_is_off_on_a_shared_bearer_bind():
+    """One bearer for every caller would make a list everyone's prompts."""
+    server = _server()
+    server.config.expose_session_listing = False
+    transport = httpx.ASGITransport(app=server.app)
+    async with httpx.AsyncClient(transport=transport, base_url="http://test") as client:
+        assert (await client.get("/v1/uhp")).json()["capabilities"]["session_listing"] is False
+        for path in ("/v1/sessions", "/v1/sessions/hsess1", "/v1/sessions/hsess1/turns"):
+            response = await client.get(path)
+            assert response.status_code == 404, path
+
+
+def test_byok_bind_defaults_session_listing_off():
+    from superqode.harness.uhp_server import create_uhp_server
+
+    byok = create_uhp_server(require_caller_provider_key=True, runner=_echo_runner)
+    local = create_uhp_server(runner=_echo_runner)
+    assert byok.config.expose_session_listing is False
+    assert local.config.expose_session_listing is True
+
+
+@pytest.mark.anyio
+async def test_bad_limit_answers_in_the_uhp_error_envelope():
+    """A validation failure must not leak the framework's own error shape."""
+    server = _server()
+    transport = httpx.ASGITransport(app=server.app)
+    async with httpx.AsyncClient(transport=transport, base_url="http://test") as client:
+        response = await client.get("/v1/sessions?limit=abc")
+    assert response.status_code == 400
+    error = response.json()["error"]
+    assert error["code"] == "invalid_input"
+    assert error["param"] == "limit"