move / dedup some wf_mcp things

src/wf_api/__init__.py

@@ -1,6 +1,25 @@
 from __future__ import annotations
 
 from .backend import TraceRange, WorkflowApiBackend
+from .constants import (
+    DEFAULT_CALL_STEP_ID,
+    DEFAULT_ERROR_OUTCOME,
+    DEFAULT_ERROR_STEP_ID,
+    DEFAULT_OK_OUTCOME,
+    RUNTIME_ERROR_CAPABILITY,
+)
+from .refs import WorkflowSurfaceCapabilityId, parse_workflow_surface_capability_id
 from .service import WorkflowApi
 
-__all__ = ["TraceRange", "WorkflowApi", "WorkflowApiBackend"]
+__all__ = [
+    "DEFAULT_CALL_STEP_ID",
+    "DEFAULT_ERROR_OUTCOME",
+    "DEFAULT_ERROR_STEP_ID",
+    "DEFAULT_OK_OUTCOME",
+    "RUNTIME_ERROR_CAPABILITY",
+    "TraceRange",
+    "WorkflowApi",
+    "WorkflowApiBackend",
+    "WorkflowSurfaceCapabilityId",
+    "parse_workflow_surface_capability_id",
+]

src/wf_api/constants.py

@@ -0,0 +1,15 @@
+"""Protocol-neutral workflow API literals used by draft/helper code."""
+
+DEFAULT_CALL_STEP_ID = "call"
+DEFAULT_ERROR_STEP_ID = "tool_error"
+DEFAULT_OK_OUTCOME = "ok"
+DEFAULT_ERROR_OUTCOME = "error"
+RUNTIME_ERROR_CAPABILITY = "wf.std.runtime_error"
+
+__all__ = [
+    "DEFAULT_CALL_STEP_ID",
+    "DEFAULT_ERROR_OUTCOME",
+    "DEFAULT_ERROR_STEP_ID",
+    "DEFAULT_OK_OUTCOME",
+    "RUNTIME_ERROR_CAPABILITY",
+]

src/wf_api/refs.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from typing import Any, TypeAlias
+
+from wf_artifacts import WorkflowCapabilityRef
+from wf_platform import CapabilityRef
+
+WorkflowSurfaceCapabilityId: TypeAlias = CapabilityRef | WorkflowCapabilityRef
+
+
+def parse_workflow_surface_capability_id(
+    value: str | dict[str, Any],
+) -> WorkflowSurfaceCapabilityId:
+    """Parse a workflow API capability id into its real domain ref.
+
+    API callers still pass strings at protocol boundaries. Internally,
+    workflow-facing capability ids are either live source capabilities or saved
+    wrapper artifacts, so this parser avoids inventing a third identifier model.
+    """
+    if isinstance(value, dict):
+        if "artifact_id" in value and "version" in value:
+            return WorkflowCapabilityRef._validate(value)
+        return CapabilityRef._validate(value)
+
+    try:
+        return WorkflowCapabilityRef.parse(value)
+    except ValueError:
+        return CapabilityRef.parse(value)

src/wf_mcp/workflow_surface/constants.py

@@ -1,10 +1,16 @@
-"""Shared workflow-surface literals used by generated draft helpers."""
+"""Compatibility shim for workflow API constants.
 
-DEFAULT_CALL_STEP_ID = "call"
+New code should import these literals from `wf_api.constants`. This module stays
-DEFAULT_ERROR_STEP_ID = "tool_error"
+so older MCP workflow-surface imports keep working during extraction.
-DEFAULT_OK_OUTCOME = "ok"
+"""
-DEFAULT_ERROR_OUTCOME = "error"
+
-RUNTIME_ERROR_CAPABILITY = "wf.std.runtime_error"
+from wf_api.constants import (
+    DEFAULT_CALL_STEP_ID,
+    DEFAULT_ERROR_OUTCOME,
+    DEFAULT_ERROR_STEP_ID,
+    DEFAULT_OK_OUTCOME,
+    RUNTIME_ERROR_CAPABILITY,
+)
 
 __all__ = [
     "DEFAULT_CALL_STEP_ID",

src/wf_mcp/workflow_surface/handlers.py

@@ -47,20 +47,21 @@ from wf_core.models.steps import (
 )
 from wf_core.paths import GraphSourcePath, LocalPath, StatePath
 
-from ..broker.service.adapters import require_adapter
+from wf_api.constants import (
-from ..events import make_event
-from ..models import RawWorkflowPlan
-from ..shared import matches_query, paged_list_payload
-from .constants import (
     DEFAULT_CALL_STEP_ID,
     DEFAULT_ERROR_OUTCOME,
     DEFAULT_ERROR_STEP_ID,
     DEFAULT_OK_OUTCOME,
     RUNTIME_ERROR_CAPABILITY,
 )
+from wf_api.refs import parse_workflow_surface_capability_id
+
+from ..broker.service.adapters import require_adapter
+from ..events import make_event
+from ..models import RawWorkflowPlan
+from ..shared import matches_query, paged_list_payload
 from .models import TraceRange
 from .next_actions import NextActions
-from .refs import parse_workflow_surface_capability_id
 from .saved_subgraphs import (
     SavedSubgraphTree,
     direct_wrapper_interrupt_diagnostic,

src/wf_mcp/workflow_surface/refs.py

@@ -1,28 +1,15 @@
-from __future__ import annotations
+"""Compatibility shim for workflow API capability refs.
 
-from typing import Any, TypeAlias
+New code should import from `wf_api.refs`. This module stays so older MCP
-
+workflow-surface imports keep working during extraction.
-from wf_artifacts import WorkflowCapabilityRef
-from wf_platform import CapabilityRef
-
-WorkflowSurfaceCapabilityId: TypeAlias = CapabilityRef | WorkflowCapabilityRef
-
-
-def parse_workflow_surface_capability_id(
-    value: str | dict[str, Any],
-) -> 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.
 """
-    if isinstance(value, dict):
-        if "artifact_id" in value and "version" in value:
-            return WorkflowCapabilityRef._validate(value)
-        return CapabilityRef._validate(value)
 
-    try:
+from wf_api.refs import (
-        return WorkflowCapabilityRef.parse(value)
+    WorkflowSurfaceCapabilityId,
-    except ValueError:
+    parse_workflow_surface_capability_id,
-        return CapabilityRef.parse(value)
+)
+
+__all__ = [
+    "WorkflowSurfaceCapabilityId",
+    "parse_workflow_surface_capability_id",
+]

tests/wf_mcp/test_workflow_surface_refs.py

@@ -1,7 +1,10 @@
 from __future__ import annotations
 
+from wf_api.refs import parse_workflow_surface_capability_id
 from wf_artifacts import WorkflowCapabilityRef
-from wf_mcp.workflow_surface.refs import parse_workflow_surface_capability_id
+from wf_mcp.workflow_surface.refs import (
+    parse_workflow_surface_capability_id as parse_workflow_surface_capability_id_shim,
+)
 from wf_platform import CapabilityRef
 
 
@@ -46,3 +49,17 @@ def test_workflow_surface_capability_id_parses_structural_saved_wrapper_ref() ->
 
     assert isinstance(capability, WorkflowCapabilityRef)
     assert str(capability) == "workflow.echo_wrapper.v2"
+
+
+def test_workflow_surface_refs_shim_reexports_canonical_parser() -> None:
+    assert parse_workflow_surface_capability_id_shim is parse_workflow_surface_capability_id
+
+
+def test_workflow_surface_constants_shim_reexports_canonical_literals() -> None:
+    from wf_api.constants import DEFAULT_CALL_STEP_ID
+    from wf_mcp.workflow_surface.constants import (
+        DEFAULT_CALL_STEP_ID as DEFAULT_CALL_STEP_ID_SHIM,
+    )
+
+    assert DEFAULT_CALL_STEP_ID_SHIM == DEFAULT_CALL_STEP_ID
+