feat: add source admin api surface

src/wf_api/__init__.py

@@ -18,6 +18,7 @@ from .next_actions import NextActionPatchExample, NextActionTool, NextActions
 from .refs import WorkflowSurfaceCapabilityId, parse_workflow_surface_capability_id
 from .runs import WorkflowRunApi
 from .service import WorkflowApi
+from .source_admin import WorkflowSourceAdminApi
 from .surface import (
     WorkflowApiSurface,
     WorkflowArtifactSurface,
@@ -25,6 +26,7 @@ from .surface import (
     WorkflowDeploymentSurface,
     WorkflowDraftSurface,
     WorkflowRunSurface,
+    WorkflowSourceAdminSurface,
 )
 from .wrapper_hints import (
     MissingDecision,
@@ -87,6 +89,8 @@ __all__ = [
     "WorkflowRuntimeRunner",
     "WorkflowRunApi",
     "WorkflowRunSurface",
+    "WorkflowSourceAdminApi",
+    "WorkflowSourceAdminSurface",
     "WorkflowSpecProvider",
     "WorkflowSurfaceCapabilityId",
     "WrapperAuthoringHints",

src/wf_api/source_admin.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from typing import Any
+
+from wf_platform import page_items
+
+from .operation_context import WorkflowOperationContext
+
+
+class WorkflowSourceAdminApi:
+    """Read-only protocol-neutral source inventory operations.
+
+    This is a sibling to WorkflowApi, not part of WorkflowApiSurface, because
+    source administration is server/platform management rather than workflow
+    lifecycle execution.
+    """
+
+    def __init__(self, context: WorkflowOperationContext) -> None:
+        self.context = context
+
+    async def list_sources(
+        self,
+        *,
+        cursor: str | None = None,
+        limit: int = 50,
+    ) -> dict[str, Any]:
+        summaries = [
+            source.as_status().model_dump(mode="json")
+            for source in sorted(
+                self.context.specs.capability_sources.values(),
+                key=lambda source: source.id,
+            )
+        ]
+        page = page_items(summaries, cursor=cursor, limit=limit)
+        return {
+            "sources": list(page.items),
+            "next_cursor": page.next_cursor,
+            "total": page.total,
+        }
+
+    async def inspect_source(self, *, source_id: str) -> dict[str, Any]:
+        try:
+            source = self.context.specs.capability_sources[source_id]
+        except KeyError as exc:
+            raise KeyError(f"unknown source {source_id!r}") from exc
+        return source.as_inventory().model_dump(mode="json")

src/wf_api/surface.py

@@ -199,6 +199,23 @@ class WorkflowApiSurface(
     """Public workflow operation surface shared by local and remote adapters."""
 
 
+class WorkflowSourceAdminSurface(Protocol):
+    """Read-only source/admin methods exposed by platform frontends."""
+
+    async def list_sources(
+        self,
+        *,
+        cursor: str | None = None,
+        limit: int = 50,
+    ) -> dict[str, Any]: ...
+
+    async def inspect_source(
+        self,
+        *,
+        source_id: str,
+    ) -> dict[str, Any]: ...
+
+
 __all__ = [
     "WorkflowApiSurface",
     "WorkflowArtifactSurface",
@@ -206,4 +223,5 @@ __all__ = [
     "WorkflowDeploymentSurface",
     "WorkflowDraftSurface",
     "WorkflowRunSurface",
+    "WorkflowSourceAdminSurface",
 ]