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)