now that looks better as a type

src/wf_mcp/workflow_surface/handlers.py

@@ -42,7 +42,7 @@ from .constants import (
     DEFAULT_OK_OUTCOME,
     RUNTIME_ERROR_CAPABILITY,
 )
-from .refs import WorkflowSurfaceCapabilityId
+from .refs import parse_workflow_surface_capability_id
 
 if TYPE_CHECKING:
     from ..broker.service import WfMcpService
@@ -161,20 +161,18 @@ class WorkflowSurfaceHandlers:
     ) -> WorkflowArtifact | None:
         """Resolve a saved node-like wrapper artifact from its stable capability name."""
         try:
-            capability_id = WorkflowSurfaceCapabilityId.parse(qualified_name)
+            capability_id = parse_workflow_surface_capability_id(qualified_name)
         except ValueError:
             return None
         if (
-            not capability_id.is_wrapper_artifact
+            not isinstance(capability_id, WorkflowCapabilityRef)
             or self.service.artifact_store is None
-            or capability_id.artifact_id is None
-            or capability_id.artifact_version is None
         ):
             return None
         try:
             artifact = self.service.artifact_store.get_artifact(
                 capability_id.artifact_id,
-                capability_id.artifact_version,
+                capability_id.version,
             )
         except KeyError:
             return None
@@ -995,12 +993,12 @@ def _source_id_for_capability(
 def _capability_name(qualified_name: str) -> str | None:
     """Return the local name of one qualified capability ref if it is valid."""
     try:
-        parsed = WorkflowSurfaceCapabilityId.parse(qualified_name)
+        parsed = parse_workflow_surface_capability_id(qualified_name)
     except ValueError:
         return None
-    if parsed.is_wrapper_artifact:
+    if isinstance(parsed, WorkflowCapabilityRef):
         return None
-    return parsed.live_name
+    return parsed.name
 
 
 def _artifact_capability_id(artifact: WorkflowArtifact) -> str:

src/wf_mcp/workflow_surface/refs.py

@@ -1,46 +1,21 @@
 from __future__ import annotations
 
-from dataclasses import dataclass
+from typing import TypeAlias
 
 from wf_artifacts import WorkflowCapabilityRef
 from wf_platform import CapabilityRef
 
+WorkflowSurfaceCapabilityId: TypeAlias = CapabilityRef | WorkflowCapabilityRef
 
-@dataclass(frozen=True, slots=True)
-class WorkflowSurfaceCapabilityId:
-    """Typed internal form for workflow-surface capability names.
 
-    MCP tools still accept and return plain strings. This type is an internal
-    boundary so handlers can distinguish live source capabilities from saved
-    wrapper artifacts without repeating ad hoc string parsing.
+def parse_workflow_surface_capability_id(value: str) -> WorkflowSurfaceCapabilityId:
+    """Parse a workflow-surface capability name into its real domain ref.
+
+    MCP tools still accept and return plain strings. Internally, workflow-facing
+    capability ids are either live source capabilities or saved wrapper
+    artifacts, so this parser avoids inventing a third identifier model.
     """
-
-    qualified_name: str
-    source_id: str
-    live_name: str | None = None
-    artifact_id: str | None = None
-    artifact_version: int | None = None
-
-    @classmethod
-    def parse(cls, value: str) -> WorkflowSurfaceCapabilityId:
-        """Parse one workflow-facing capability id into its internal kind."""
-        try:
-            artifact_ref = WorkflowCapabilityRef.parse(value)
-        except ValueError:
-            capability_ref = CapabilityRef.parse(value)
-            return cls(
-                qualified_name=str(capability_ref),
-                source_id=str(capability_ref.source),
-                live_name=capability_ref.name,
-            )
-        return cls(
-            qualified_name=str(artifact_ref),
-            source_id="workflow",
-            artifact_id=artifact_ref.artifact_id,
-            artifact_version=artifact_ref.version,
-        )
-
-    @property
-    def is_wrapper_artifact(self) -> bool:
-        """Return whether this id targets a saved workflow wrapper artifact."""
-        return self.artifact_id is not None
+    try:
+        return WorkflowCapabilityRef.parse(value)
+    except ValueError:
+        return CapabilityRef.parse(value)

tests/wf_mcp/test_workflow_surface_refs.py

@@ -1,22 +1,23 @@
 from __future__ import annotations
 
-from wf_mcp.workflow_surface.refs import WorkflowSurfaceCapabilityId
+from wf_artifacts import WorkflowCapabilityRef
+from wf_mcp.workflow_surface.refs import parse_workflow_surface_capability_id
+from wf_platform import CapabilityRef
 
 
 def test_workflow_surface_capability_id_parses_live_capability_ref() -> None:
-    capability = WorkflowSurfaceCapabilityId.parse("demo.personal.echo_tool")
+    capability = parse_workflow_surface_capability_id("demo.personal.echo_tool")
 
-    assert capability.qualified_name == "demo.personal.echo_tool"
-    assert capability.source_id == "demo.personal"
-    assert capability.live_name == "echo_tool"
-    assert capability.is_wrapper_artifact is False
+    assert isinstance(capability, CapabilityRef)
+    assert str(capability) == "demo.personal.echo_tool"
+    assert str(capability.source) == "demo.personal"
+    assert capability.name == "echo_tool"
 
 
 def test_workflow_surface_capability_id_parses_saved_wrapper_ref() -> None:
-    capability = WorkflowSurfaceCapabilityId.parse("workflow.echo_wrapper.v2")
+    capability = parse_workflow_surface_capability_id("workflow.echo_wrapper.v2")
 
-    assert capability.qualified_name == "workflow.echo_wrapper.v2"
-    assert capability.source_id == "workflow"
+    assert isinstance(capability, WorkflowCapabilityRef)
+    assert str(capability) == "workflow.echo_wrapper.v2"
     assert capability.artifact_id == "echo_wrapper"
-    assert capability.artifact_version == 2
-    assert capability.is_wrapper_artifact is True
+    assert capability.version == 2