1501 lines
45 KiB
Markdown
1501 lines
45 KiB
Markdown
# [INVALID] wf_api Slice 1: Dependency Direction — Implementation Plan
|
|
|
|
> **INVALID — replaced by `2026-06-01-wf-api-slice-1-dependency-direction.md`.**
|
|
>
|
|
> **Why this plan is wrong:** It moves 13 helper modules (`constants`, `refs`, `next_actions`, `wrapper_hints`, `saved_subgraphs`, `run_lifecycle`, `runtime_dependencies`, `events`, `listing`, `models`) into `wf_api` before the extraction seam is proven. That is a large, risky blast radius for a "dependency direction only" slice. It also defines `WorkflowApiBackend` as a low-level store/execution port rather than a high-level operation protocol, which means the facade does real work instead of delegating. The replacement plan keeps the existing `WorkflowSurfaceHandlers` implementation in `wf_mcp`, wraps it behind a high-level `WorkflowApiBackend` protocol, and introduces `wf_api` as a thin delegating facade — zero helper migration, zero response shape risk.
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
|
|
**Goal:** Make both CLI and MCP call a protocol-neutral `WorkflowApi` while `wf_api` imports zero `wf_mcp` modules.
|
|
|
|
**Architecture:** `WorkflowApi` (renamed `WorkflowSurfaceHandlers`) takes a `WorkflowApiBackend` protocol instead of `WfMcpService`. `WfMcpWorkflowApiBackend` adapts `WfMcpService` into that protocol. Helper modules that `WorkflowApi` needs move from `wf_mcp.workflow_surface` to `wf_api` because they are protocol-neutral and their current location would create `wf_api -> wf_mcp` imports.
|
|
|
|
**Tech Stack:** Python 3.12+, pydantic, anyio, existing `wf_artifacts`/`wf_platform`/`wf_authoring`/`wf_core` packages.
|
|
|
|
---
|
|
|
|
## Import Direction Rules
|
|
|
|
After this plan is complete, the following rules hold:
|
|
|
|
```text
|
|
wf_api -> wf_artifacts, wf_platform, wf_authoring, wf_core (OK)
|
|
wf_api -> wf_mcp (FORBIDDEN)
|
|
wf_mcp -> wf_api (OK — adapter direction)
|
|
wf_cli -> wf_api (OK)
|
|
wf_cli -> wf_mcp (OK — config/service construction only)
|
|
```
|
|
|
|
## File Structure
|
|
|
|
### New files to create
|
|
|
|
| File | Responsibility |
|
|
|------|---------------|
|
|
| `src/wf_api/__init__.py` | Package root; re-exports `WorkflowApi`, `WorkflowApiBackend` |
|
|
| `src/wf_api/backend.py` | `WorkflowApiBackend` protocol |
|
|
| `src/wf_api/service.py` | `WorkflowApi` class (body from `WorkflowSurfaceHandlers`) |
|
|
| `src/wf_api/events.py` | `McpEvent` dataclass + `make_event` factory (moved from `wf_mcp.events.models`) |
|
|
| `src/wf_api/listing.py` | `matches_query`, `paged_list_payload` (moved from `wf_mcp.shared.listing`) |
|
|
| `src/wf_api/models.py` | `RawWorkflowPlan`, `TraceRange` (moved from `wf_mcp.models` + `wf_mcp.workflow_surface.models`) |
|
|
| `src/wf_api/constants.py` | Draft helper constants (moved from `wf_mcp.workflow_surface.constants`) |
|
|
| `src/wf_api/refs.py` | `parse_workflow_surface_capability_id` (moved from `wf_mcp.workflow_surface.refs`) |
|
|
| `src/wf_api/next_actions.py` | `NextActions`, `NextActionTool` (moved from `wf_mcp.workflow_surface.next_actions`) |
|
|
| `src/wf_api/wrapper_hints.py` | `wrapper_hints_for_capability` etc. (moved from `wf_mcp.workflow_surface.wrapper_hints`) |
|
|
| `src/wf_api/runtime_dependencies.py` | `resolve_runtime_dependencies` (moved from `wf_mcp.workflow_surface.runtime_dependencies`) |
|
|
| `src/wf_api/saved_subgraphs.py` | `SavedSubgraphTree` etc. (moved from `wf_mcp.workflow_surface.saved_subgraphs`) |
|
|
| `src/wf_api/run_lifecycle.py` | `persist_stopped_run`, `create_pinned_environment` etc. (moved from `wf_mcp.workflow_surface.run_lifecycle`) |
|
|
| `src/wf_mcp/broker/service/workflow_api_backend.py` | `WfMcpWorkflowApiBackend` adapter |
|
|
|
|
### Files to modify
|
|
|
|
| File | Change |
|
|
|------|--------|
|
|
| `src/wf_mcp/workflow_surface/handlers.py` | Replace with thin shim: re-export from `wf_api.service` |
|
|
| `src/wf_mcp/workflow_surface/constants.py` | Replace with thin shim: re-export from `wf_api.constants` |
|
|
| `src/wf_mcp/workflow_surface/refs.py` | Replace with thin shim: re-export from `wf_api.refs` |
|
|
| `src/wf_mcp/workflow_surface/next_actions.py` | Replace with thin shim: re-export from `wf_api.next_actions` |
|
|
| `src/wf_mcp/workflow_surface/wrapper_hints.py` | Replace with thin shim: re-export from `wf_api.wrapper_hints` |
|
|
| `src/wf_mcp/workflow_surface/runtime_dependencies.py` | Replace with thin shim: re-export from `wf_api.runtime_dependencies` |
|
|
| `src/wf_mcp/workflow_surface/saved_subgraphs.py` | Replace with thin shim: re-export from `wf_api.saved_subgraphs` |
|
|
| `src/wf_mcp/workflow_surface/run_lifecycle.py` | Replace with thin shim: re-export from `wf_api.run_lifecycle` |
|
|
| `src/wf_mcp/workflow_surface/models.py` | Update `NextActions` import to `wf_api.next_actions` |
|
|
| `src/wf_mcp/workflow_surface/tools.py` | Import `TraceRange` from `wf_api.models`, `WorkflowApi` from `wf_api.service` |
|
|
| `src/wf_mcp/workflow_surface/__init__.py` | Keep re-exports (shims make them work) |
|
|
| `src/wf_mcp/events/models.py` | Replace with thin shim: re-export from `wf_api.events` |
|
|
| `src/wf_mcp/shared/listing.py` | Replace with thin shim: re-export from `wf_api.listing` |
|
|
| `src/wf_mcp/shared/__init__.py` | Update `matches_query`/`paged_list_payload` import path |
|
|
| `src/wf_cli/context.py` | Import `WorkflowApi` from `wf_api.service` |
|
|
| `src/wf_cli/commands/runs.py` | Import `TraceRange` from `wf_api.models` |
|
|
| `pyproject.toml` | Add `wf_api` to packages list |
|
|
|
|
### Files NOT to modify
|
|
|
|
- `tests/` — shim re-exports preserve all existing import paths; tests pass unchanged
|
|
- `examples/` — same; `from wf_mcp.workflow_surface import WorkflowSurfaceHandlers` still works via shim
|
|
- `src/wf_mcp/broker/service/core.py` — `WfMcpService` is unchanged
|
|
- `src/wf_mcp/workflow_surface/tools.py` internals — only import paths change; tool registration logic unchanged
|
|
|
|
---
|
|
|
|
## Risk: Where the Roadmap Might Be Wrong
|
|
|
|
1. **The roadmap says "keep helper modules in place."** That is not possible for Slice 1. `wf_api.service` imports `constants`, `refs`, `next_actions`, `wrapper_hints`, `saved_subgraphs`, `run_lifecycle`, `runtime_dependencies`, `matches_query`, `paged_list_payload`, `make_event`, and `RawWorkflowPlan` — all from `wf_mcp.*` today. To establish the `wf_api -/-> wf_mcp` rule, these must move. The extraction map confirms this. The roadmap's "not allowed: do not move every helper module yet" is aspirational for later slices but wrong for this one.
|
|
|
|
2. **The roadmap puts `WfMcpWorkflowApiBackend` in `src/wf_mcp/broker/service/workflow_api_backend.py`.** This is fine but the adapter needs access to `_live_source_diagnostics` (MCP connections/adapters/auth). The plan keeps that function inside the adapter rather than importing it from the old `handlers.py` shim, because the shim re-exports from `wf_api.service` which no longer contains MCP-specific code.
|
|
|
|
3. **`McpEvent` naming.** The roadmap defers renaming to Slice 2. This plan keeps the name `McpEvent` but moves it to `wf_api.events`. The rename to `DomainEvent` is a Slice 2 concern.
|
|
|
|
4. **`wf_mcp.workflow_surface.models` stays in `wf_mcp`.** It contains MCP tool request/response pydantic models (507 lines) that `tools.py` needs. Only the `NextActions` import path changes. `TraceRange` is re-exported via the `__init__.py` shim.
|
|
|
|
---
|
|
|
|
## Task 1: Create `wf_api` package root
|
|
|
|
**Files:**
|
|
|
|
- Create: `src/wf_api/__init__.py`
|
|
|
|
- [ ] **Step 1: Create the package directory**
|
|
|
|
```bash
|
|
mkdir -p src/wf_api
|
|
```
|
|
|
|
- [ ] **Step 2: Write `__init__.py`**
|
|
|
|
```python
|
|
from __future__ import annotations
|
|
|
|
from .backend import WorkflowApiBackend
|
|
from .service import WorkflowApi
|
|
|
|
__all__ = ["WorkflowApi", "WorkflowApiBackend"]
|
|
```
|
|
|
|
- [ ] **Step 3: Verify import**
|
|
|
|
```bash
|
|
uv run python -c "from wf_api import WorkflowApi, WorkflowApiBackend; print('OK')"
|
|
```
|
|
|
|
Expected: `OK` (will fail until later tasks populate the modules — that's fine; create the file now and revisit).
|
|
|
|
- [ ] **Step 4: Commit**
|
|
|
|
```bash
|
|
git add src/wf_api/__init__.py
|
|
git commit -m "feat(wf_api): create package root with re-exports"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 2: Move protocol-neutral helper modules to `wf_api`
|
|
|
|
These modules have zero `wf_mcp` imports. Moving them is a prerequisite for `wf_api.service` to not import `wf_mcp`.
|
|
|
|
### Task 2a: Move `constants`
|
|
|
|
**Files:**
|
|
|
|
- Create: `src/wf_api/constants.py`
|
|
- Modify: `src/wf_mcp/workflow_surface/constants.py` → shim
|
|
|
|
- [ ] **Step 1: Create `src/wf_api/constants.py`**
|
|
|
|
```python
|
|
"""Shared workflow-surface literals used by generated draft helpers."""
|
|
|
|
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",
|
|
]
|
|
```
|
|
|
|
- [ ] **Step 2: Replace `src/wf_mcp/workflow_surface/constants.py` with shim**
|
|
|
|
```python
|
|
"""Backward-compatibility shim — canonical location is wf_api.constants."""
|
|
|
|
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",
|
|
"DEFAULT_ERROR_OUTCOME",
|
|
"DEFAULT_ERROR_STEP_ID",
|
|
"DEFAULT_OK_OUTCOME",
|
|
"RUNTIME_ERROR_CAPABILITY",
|
|
]
|
|
```
|
|
|
|
- [ ] **Step 3: Verify existing tests still pass**
|
|
|
|
```bash
|
|
uv run pytest tests/wf_mcp/workflow_surface/test_drafts.py -q
|
|
```
|
|
|
|
Expected: all pass (imports route through shim).
|
|
|
|
- [ ] **Step 4: Commit**
|
|
|
|
```bash
|
|
git add src/wf_api/constants.py src/wf_mcp/workflow_surface/constants.py
|
|
git commit -m "refactor: move constants to wf_api, leave shim in wf_mcp"
|
|
```
|
|
|
|
### Task 2b: Move `wrapper_hints`
|
|
|
|
**Files:**
|
|
|
|
- Create: `src/wf_api/wrapper_hints.py`
|
|
- Modify: `src/wf_mcp/workflow_surface/wrapper_hints.py` → shim
|
|
|
|
- [ ] **Step 1: Copy `src/wf_mcp/workflow_surface/wrapper_hints.py` to `src/wf_api/wrapper_hints.py`**
|
|
|
|
Use `read` to get the full file content, then `write` it to the new location. Verify the file has no `wf_mcp` imports (it should only import from `pydantic`, `enum`, `typing`).
|
|
|
|
- [ ] **Step 2: Replace old file with shim**
|
|
|
|
```python
|
|
"""Backward-compatibility shim — canonical location is wf_api.wrapper_hints."""
|
|
|
|
from wf_api.wrapper_hints import * # noqa: F401,F403
|
|
```
|
|
|
|
- [ ] **Step 3: Verify**
|
|
|
|
```bash
|
|
uv run pytest tests/wf_mcp/test_workflow_wrapper_hints.py -q
|
|
```
|
|
|
|
Expected: all pass.
|
|
|
|
- [ ] **Step 4: Commit**
|
|
|
|
```bash
|
|
git add src/wf_api/wrapper_hints.py src/wf_mcp/workflow_surface/wrapper_hints.py
|
|
git commit -m "refactor: move wrapper_hints to wf_api, leave shim"
|
|
```
|
|
|
|
### Task 2c: Move `refs`
|
|
|
|
**Files:**
|
|
|
|
- Create: `src/wf_api/refs.py`
|
|
- Modify: `src/wf_mcp/workflow_surface/refs.py` → shim
|
|
|
|
- [ ] **Step 1: Copy `src/wf_mcp/workflow_surface/refs.py` to `src/wf_api/refs.py`**
|
|
|
|
Verify: imports only from `wf_artifacts` and `wf_platform`.
|
|
|
|
- [ ] **Step 2: Replace old file with shim**
|
|
|
|
```python
|
|
"""Backward-compatibility shim — canonical location is wf_api.refs."""
|
|
|
|
from wf_api.refs import * # noqa: F401,F403
|
|
```
|
|
|
|
- [ ] **Step 3: Verify**
|
|
|
|
```bash
|
|
uv run pytest tests/wf_mcp/test_workflow_surface_refs.py -q
|
|
```
|
|
|
|
Expected: all pass.
|
|
|
|
- [ ] **Step 4: Commit**
|
|
|
|
```bash
|
|
git add src/wf_api/refs.py src/wf_mcp/workflow_surface/refs.py
|
|
git commit -m "refactor: move refs to wf_api, leave shim"
|
|
```
|
|
|
|
### Task 2d: Move `next_actions`
|
|
|
|
**Files:**
|
|
|
|
- Create: `src/wf_api/next_actions.py`
|
|
- Modify: `src/wf_mcp/workflow_surface/next_actions.py` → shim
|
|
|
|
- [ ] **Step 1: Copy `src/wf_mcp/workflow_surface/next_actions.py` to `src/wf_api/next_actions.py`**
|
|
|
|
Update the internal import: change `from .wrapper_hints import WrapperAuthoringHints` to `from wf_api.wrapper_hints import WrapperAuthoringHints`.
|
|
|
|
- [ ] **Step 2: Replace old file with shim**
|
|
|
|
```python
|
|
"""Backward-compatibility shim — canonical location is wf_api.next_actions."""
|
|
|
|
from wf_api.next_actions import * # noqa: F401,F403
|
|
```
|
|
|
|
- [ ] **Step 3: Verify**
|
|
|
|
```bash
|
|
uv run pytest tests/wf_mcp/workflow_surface/test_next_actions.py -q
|
|
```
|
|
|
|
Expected: all pass.
|
|
|
|
- [ ] **Step 4: Commit**
|
|
|
|
```bash
|
|
git add src/wf_api/next_actions.py src/wf_mcp/workflow_surface/next_actions.py
|
|
git commit -m "refactor: move next_actions to wf_api, leave shim"
|
|
```
|
|
|
|
### Task 2e: Move `runtime_dependencies`
|
|
|
|
**Files:**
|
|
|
|
- Create: `src/wf_api/runtime_dependencies.py`
|
|
- Modify: `src/wf_mcp/workflow_surface/runtime_dependencies.py` → shim
|
|
|
|
- [ ] **Step 1: Copy `src/wf_mcp/workflow_surface/runtime_dependencies.py` to `src/wf_api/runtime_dependencies.py`**
|
|
|
|
Verify: imports only from `wf_artifacts`, `wf_authoring`, `wf_core`, `wf_platform`. No changes needed.
|
|
|
|
- [ ] **Step 2: Replace old file with shim**
|
|
|
|
```python
|
|
"""Backward-compatibility shim — canonical location is wf_api.runtime_dependencies."""
|
|
|
|
from wf_api.runtime_dependencies import * # noqa: F401,F403
|
|
```
|
|
|
|
- [ ] **Step 3: Commit**
|
|
|
|
```bash
|
|
git add src/wf_api/runtime_dependencies.py src/wf_mcp/workflow_surface/runtime_dependencies.py
|
|
git commit -m "refactor: move runtime_dependencies to wf_api, leave shim"
|
|
```
|
|
|
|
### Task 2f: Move `saved_subgraphs`
|
|
|
|
**Files:**
|
|
|
|
- Create: `src/wf_api/saved_subgraphs.py`
|
|
- Modify: `src/wf_mcp/workflow_surface/saved_subgraphs.py` → shim
|
|
|
|
- [ ] **Step 1: Copy `src/wf_mcp/workflow_surface/saved_subgraphs.py` to `src/wf_api/saved_subgraphs.py`**
|
|
|
|
Update internal imports:
|
|
|
|
- `from ..models import RawWorkflowPlan` → `from wf_api.models import RawWorkflowPlan`
|
|
- `from .runtime_dependencies import resolve_runtime_dependencies` → `from wf_api.runtime_dependencies import resolve_runtime_dependencies`
|
|
|
|
- [ ] **Step 2: Replace old file with shim**
|
|
|
|
```python
|
|
"""Backward-compatibility shim — canonical location is wf_api.saved_subgraphs."""
|
|
|
|
from wf_api.saved_subgraphs import * # noqa: F401,F403
|
|
```
|
|
|
|
- [ ] **Step 3: Verify**
|
|
|
|
```bash
|
|
uv run pytest tests/wf_mcp/test_saved_subgraphs.py -q
|
|
```
|
|
|
|
Expected: all pass.
|
|
|
|
- [ ] **Step 4: Commit**
|
|
|
|
```bash
|
|
git add src/wf_api/saved_subgraphs.py src/wf_mcp/workflow_surface/saved_subgraphs.py
|
|
git commit -m "refactor: move saved_subgraphs to wf_api, leave shim"
|
|
```
|
|
|
|
### Task 2g: Move `run_lifecycle`
|
|
|
|
**Files:**
|
|
|
|
- Create: `src/wf_api/run_lifecycle.py`
|
|
- Modify: `src/wf_mcp/workflow_surface/run_lifecycle.py` → shim
|
|
|
|
- [ ] **Step 1: Copy `src/wf_mcp/workflow_surface/run_lifecycle.py` to `src/wf_api/run_lifecycle.py`**
|
|
|
|
Update internal import:
|
|
|
|
- `from .saved_subgraphs import SavedSubgraphTree` → `from wf_api.saved_subgraphs import SavedSubgraphTree`
|
|
|
|
- [ ] **Step 2: Replace old file with shim**
|
|
|
|
```python
|
|
"""Backward-compatibility shim — canonical location is wf_api.run_lifecycle."""
|
|
|
|
from wf_api.run_lifecycle import * # noqa: F401,F403
|
|
```
|
|
|
|
- [ ] **Step 3: Commit**
|
|
|
|
```bash
|
|
git add src/wf_api/run_lifecycle.py src/wf_mcp/workflow_surface/run_lifecycle.py
|
|
git commit -m "refactor: move run_lifecycle to wf_api, leave shim"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 3: Move `events` and `listing` primitives to `wf_api`
|
|
|
|
### Task 3a: Move `McpEvent` + `make_event` to `wf_api.events`
|
|
|
|
**Files:**
|
|
|
|
- Create: `src/wf_api/events.py`
|
|
- Modify: `src/wf_mcp/events/models.py` → shim
|
|
|
|
- [ ] **Step 1: Create `src/wf_api/events.py`**
|
|
|
|
Copy content from `src/wf_mcp/events/models.py`:
|
|
|
|
```python
|
|
from __future__ import annotations
|
|
|
|
import time
|
|
from dataclasses import dataclass, field
|
|
from typing import Any
|
|
|
|
|
|
@dataclass(slots=True)
|
|
class McpEvent:
|
|
"""Broker-local event record before protocol-specific projection."""
|
|
|
|
kind: str
|
|
timestamp_epoch_ms: int
|
|
connection_id: str | None = None
|
|
capability_id: str | None = None
|
|
workflow_name: str | None = None
|
|
payload: dict[str, Any] = field(default_factory=dict)
|
|
|
|
|
|
def make_event(
|
|
kind: str,
|
|
*,
|
|
connection_id: str | None = None,
|
|
capability_id: str | None = None,
|
|
workflow_name: str | None = None,
|
|
payload: dict[str, Any] | None = None,
|
|
) -> McpEvent:
|
|
"""Create a timestamped event with optional routing metadata."""
|
|
return McpEvent(
|
|
kind=kind,
|
|
timestamp_epoch_ms=int(time.time() * 1000),
|
|
connection_id=connection_id,
|
|
capability_id=capability_id,
|
|
workflow_name=workflow_name,
|
|
payload=payload or {},
|
|
)
|
|
```
|
|
|
|
- [ ] **Step 2: Replace `src/wf_mcp/events/models.py` with shim**
|
|
|
|
```python
|
|
"""Backward-compatibility shim — canonical location is wf_api.events."""
|
|
|
|
from wf_api.events import McpEvent, make_event
|
|
|
|
__all__ = ["McpEvent", "make_event"]
|
|
```
|
|
|
|
- [ ] **Step 3: Verify**
|
|
|
|
```bash
|
|
uv run pytest tests/wf_mcp/test_events.py -q
|
|
```
|
|
|
|
Expected: all pass. `wf_mcp.events.bus` imports `McpEvent` from `.models` which re-exports from `wf_api.events`.
|
|
|
|
- [ ] **Step 4: Commit**
|
|
|
|
```bash
|
|
git add src/wf_api/events.py src/wf_mcp/events/models.py
|
|
git commit -m "refactor: move McpEvent/make_event to wf_api.events, leave shim"
|
|
```
|
|
|
|
### Task 3b: Move `matches_query` + `paged_list_payload` to `wf_api.listing`
|
|
|
|
**Files:**
|
|
|
|
- Create: `src/wf_api/listing.py`
|
|
- Modify: `src/wf_mcp/shared/listing.py` → shim
|
|
|
|
- [ ] **Step 1: Create `src/wf_api/listing.py`**
|
|
|
|
Copy content from `src/wf_mcp/shared/listing.py`:
|
|
|
|
```python
|
|
from __future__ import annotations
|
|
|
|
from collections.abc import Sequence
|
|
from typing import Any, TypeVar
|
|
|
|
from wf_platform import page_items
|
|
|
|
T = TypeVar("T")
|
|
|
|
|
|
def matches_query(*values: object, query: str | None) -> bool:
|
|
"""Return whether a compact discovery row matches a human search query."""
|
|
if query is None:
|
|
return True
|
|
needle = query.strip().casefold()
|
|
if not needle:
|
|
return True
|
|
return any(needle in str(value).casefold() for value in values if value is not None)
|
|
|
|
|
|
def paged_list_payload(
|
|
key: str,
|
|
items: Sequence[T],
|
|
*,
|
|
cursor: str | None,
|
|
limit: int,
|
|
) -> dict[str, Any]:
|
|
"""Build the common workflow-surface list response shape."""
|
|
page = page_items(items, cursor=cursor, limit=limit)
|
|
return {
|
|
key: list(page.items),
|
|
"next_cursor": page.next_cursor,
|
|
"total": page.total,
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 2: Replace `src/wf_mcp/shared/listing.py` with shim**
|
|
|
|
```python
|
|
"""Backward-compatibility shim — canonical location is wf_api.listing."""
|
|
|
|
from wf_api.listing import matches_query, paged_list_payload
|
|
|
|
__all__ = ["matches_query", "paged_list_payload"]
|
|
```
|
|
|
|
- [ ] **Step 3: Update `src/wf_mcp/shared/__init__.py`**
|
|
|
|
Change the import source for `matches_query` and `paged_list_payload` from `.listing` to keep working (the shim handles it, but update for clarity):
|
|
|
|
```python
|
|
from .errors import error_payload, root_exception
|
|
from .listing import matches_query, paged_list_payload # routes through shim to wf_api
|
|
from .names import (
|
|
ADMIN_NAMESPACE,
|
|
LdaNamespace,
|
|
ProxyNamespace,
|
|
ProxyToolName,
|
|
connection_id_to_resource_path,
|
|
is_admin_tool_name,
|
|
namespaced_tool_name,
|
|
parse_namespaced_tool_name,
|
|
)
|
|
from .pagination import clamp_limit, make_cursor, paginate_items, parse_cursor
|
|
|
|
__all__ = [
|
|
"ADMIN_NAMESPACE",
|
|
"LdaNamespace",
|
|
"ProxyNamespace",
|
|
"ProxyToolName",
|
|
"connection_id_to_resource_path",
|
|
"clamp_limit",
|
|
"error_payload",
|
|
"is_admin_tool_name",
|
|
"make_cursor",
|
|
"matches_query",
|
|
"namespaced_tool_name",
|
|
"paged_list_payload",
|
|
"paginate_items",
|
|
"parse_cursor",
|
|
"parse_namespaced_tool_name",
|
|
"root_exception",
|
|
]
|
|
```
|
|
|
|
No change needed — `from .listing import ...` still works because the shim re-exports.
|
|
|
|
- [ ] **Step 4: Commit**
|
|
|
|
```bash
|
|
git add src/wf_api/listing.py src/wf_mcp/shared/listing.py
|
|
git commit -m "refactor: move listing helpers to wf_api.listing, leave shim"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 4: Move `RawWorkflowPlan` and `TraceRange` to `wf_api.models`
|
|
|
|
**Files:**
|
|
|
|
- Create: `src/wf_api/models.py`
|
|
- Modify: `src/wf_mcp/models.py` → add re-export shim for `RawWorkflowPlan`
|
|
- Modify: `src/wf_mcp/workflow_surface/models.py` → update `NextActions` import
|
|
|
|
- [ ] **Step 1: Create `src/wf_api/models.py`**
|
|
|
|
```python
|
|
from __future__ import annotations
|
|
|
|
from dataclasses import dataclass
|
|
from typing import Any
|
|
|
|
from pydantic import BaseModel, Field
|
|
from wf_core import Edge
|
|
from wf_core.models.steps import InputBinding, Step
|
|
|
|
|
|
class RawWorkflowPlan(BaseModel):
|
|
"""Raw authoring plan using the same graph step and edge models as core."""
|
|
|
|
name: str
|
|
input_schema: dict[str, Any]
|
|
state_schema: dict[str, Any]
|
|
output_schema: dict[str, Any]
|
|
outcomes: list[str] = Field(
|
|
default_factory=lambda: ["ok"],
|
|
description=(
|
|
"Declared public workflow outcomes. Legacy plans without this field "
|
|
"default to ok."
|
|
),
|
|
)
|
|
output: list[InputBinding] = Field(
|
|
default_factory=list,
|
|
description=(
|
|
"Optional root workflow output bindings. Sources read graph paths "
|
|
"such as state.result and targets write the public output payload."
|
|
),
|
|
)
|
|
start: str
|
|
nodes: list[Step]
|
|
edges: list[Edge]
|
|
|
|
|
|
@dataclass(frozen=True, slots=True)
|
|
class TraceRange:
|
|
"""Caller-bounded debug trace slice for durable deployment runs."""
|
|
|
|
start: int = 0
|
|
limit: int = 20
|
|
```
|
|
|
|
Note: `RawWorkflowPlan` content comes from `src/wf_mcp/models.py:45-68`. `TraceRange` content comes from `src/wf_mcp/workflow_surface/models.py` — grep for `class TraceRange` to get the exact definition.
|
|
|
|
- [ ] **Step 2: Add re-export shim at bottom of `src/wf_mcp/models.py`**
|
|
|
|
Append to the end of `src/wf_mcp/models.py`:
|
|
|
|
```python
|
|
# Backward-compatibility re-export — canonical location is wf_api.models
|
|
from wf_api.models import RawWorkflowPlan as RawWorkflowPlan
|
|
```
|
|
|
|
This shadows the local `RawWorkflowPlan` class. Keep the local class definition for now so other `wf_mcp` code that imports `RawWorkflowPlan` from `wf_mcp.models` continues to work. The re-export ensures `from wf_mcp.models import RawWorkflowPlan` resolves to the `wf_api` version.
|
|
|
|
**Alternative (cleaner):** Remove the local `RawWorkflowPlan` class from `wf_mcp/models.py` entirely and keep only the re-export. This is preferred if no other `wf_mcp` code defines behavior on the local class.
|
|
|
|
- [ ] **Step 3: Update `src/wf_mcp/workflow_surface/models.py` imports**
|
|
|
|
Change line 7 from:
|
|
|
|
```python
|
|
from .next_actions import NextActionPatchExample, NextActions
|
|
```
|
|
|
|
to:
|
|
|
|
```python
|
|
from wf_api.next_actions import NextActionPatchExample, NextActions
|
|
```
|
|
|
|
Also add a re-export for `TraceRange` at the bottom of the file (for `wf_mcp.workflow_surface.__init__.py`):
|
|
|
|
```python
|
|
# Backward-compatibility re-export — canonical location is wf_api.models
|
|
from wf_api.models import TraceRange as TraceRange
|
|
```
|
|
|
|
- [ ] **Step 4: Verify**
|
|
|
|
```bash
|
|
uv run pytest tests/wf_mcp/workflow_surface/test_drafts.py tests/wf_mcp/workflow_surface/test_runs.py -q
|
|
```
|
|
|
|
Expected: all pass.
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
git add src/wf_api/models.py src/wf_mcp/models.py src/wf_mcp/workflow_surface/models.py
|
|
git commit -m "refactor: move RawWorkflowPlan and TraceRange to wf_api.models"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 5: Create `WorkflowApiBackend` protocol
|
|
|
|
**Files:**
|
|
|
|
- Create: `src/wf_api/backend.py`
|
|
|
|
- [ ] **Step 1: Write `src/wf_api/backend.py`**
|
|
|
|
```python
|
|
from __future__ import annotations
|
|
|
|
from collections.abc import Sequence
|
|
from typing import Any, Protocol, runtime_checkable
|
|
|
|
from wf_artifacts import (
|
|
DraftWorkspaceStore,
|
|
RunStore,
|
|
WorkflowArtifact,
|
|
WorkflowArtifactCatalogEntry,
|
|
WorkflowArtifactStore,
|
|
WorkflowDeployment,
|
|
)
|
|
from wf_authoring import NodeSpec
|
|
from wf_platform import CapabilitySource
|
|
|
|
from .events import McpEvent
|
|
|
|
|
|
@runtime_checkable
|
|
class WorkflowApiBackend(Protocol):
|
|
"""Protocol that WorkflowApi requires from its host service.
|
|
|
|
Implementations adapt a concrete service (e.g. WfMcpService) into this
|
|
interface so that wf_api never imports wf_mcp.
|
|
"""
|
|
|
|
@property
|
|
def artifact_store(self) -> WorkflowArtifactStore | None: ...
|
|
|
|
@property
|
|
def draft_workspace_store(self) -> DraftWorkspaceStore | None: ...
|
|
|
|
@property
|
|
def run_store(self) -> RunStore | None: ...
|
|
|
|
@property
|
|
def capability_sources(self) -> dict[str, CapabilitySource]: ...
|
|
|
|
def get_qualified_spec(self, qualified_name: str) -> NodeSpec[Any, Any]:
|
|
"""Return the executable NodeSpec for a fully-qualified capability name."""
|
|
...
|
|
|
|
def record_event(self, event: McpEvent) -> None:
|
|
"""Publish one domain event."""
|
|
...
|
|
|
|
async def run_workflow_from_plan(
|
|
self,
|
|
plan: Any,
|
|
workflow_input: dict[str, Any],
|
|
*,
|
|
deployment: WorkflowDeployment | None = None,
|
|
artifact: WorkflowArtifact | None = None,
|
|
saved_subgraph_tree: Any | None = None,
|
|
) -> Any:
|
|
"""Execute a compiled workflow plan and return the run state."""
|
|
...
|
|
|
|
async def resume_workflow_from_plan(
|
|
self,
|
|
plan: Any,
|
|
run: Any,
|
|
*,
|
|
resume_payload: dict[str, Any],
|
|
resume_outcome: str = "submitted",
|
|
deployment: WorkflowDeployment | None = None,
|
|
artifact: WorkflowArtifact | None = None,
|
|
saved_subgraph_tree: Any | None = None,
|
|
) -> Any:
|
|
"""Resume a stopped workflow run."""
|
|
...
|
|
|
|
def workflow_artifact_catalog_entry(
|
|
self,
|
|
artifact: WorkflowArtifact,
|
|
) -> WorkflowArtifactCatalogEntry:
|
|
"""Project a saved artifact as a planner catalog entry."""
|
|
...
|
|
|
|
async def check_source_liveness(
|
|
self,
|
|
*,
|
|
deployment: WorkflowDeployment,
|
|
artifacts: Sequence[WorkflowArtifact],
|
|
) -> list[Any]:
|
|
"""Run opt-in live connectivity checks for bound upstream sources.
|
|
|
|
Default implementation returns empty list. MCP adapter overrides
|
|
with actual connection/adapter/auth probe.
|
|
"""
|
|
...
|
|
```
|
|
|
|
- [ ] **Step 2: Verify import**
|
|
|
|
```bash
|
|
uv run python -c "from wf_api.backend import WorkflowApiBackend; print('OK')"
|
|
```
|
|
|
|
Expected: `OK`.
|
|
|
|
- [ ] **Step 3: Commit**
|
|
|
|
```bash
|
|
git add src/wf_api/backend.py
|
|
git commit -m "feat(wf_api): add WorkflowApiBackend protocol"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 6: Create `WorkflowApi` service
|
|
|
|
**Files:**
|
|
|
|
- Create: `src/wf_api/service.py`
|
|
|
|
- [ ] **Step 1: Write `src/wf_api/service.py`**
|
|
|
|
This is the largest step. The body is `WorkflowSurfaceHandlers` from `src/wf_mcp/workflow_surface/handlers.py` with these changes:
|
|
|
|
1. **Class name:** `WorkflowSurfaceHandlers` → `WorkflowApi`
|
|
2. **Constructor:** `self.service: WfMcpService` → `self.backend: WorkflowApiBackend`
|
|
3. **All `self.service.X`** → `self.backend.X` (property access)
|
|
4. **All `self.service._get_qualified_spec(...)`** → `self.backend.get_qualified_spec(...)`
|
|
5. **All `self.service._record_event(...)`** → `self.backend.record_event(...)`
|
|
6. **All `self.service.run_workflow_from_plan(...)`** → `self.backend.run_workflow_from_plan(...)`
|
|
7. **All `self.service.resume_workflow_from_plan(...)`** → `self.backend.resume_workflow_from_plan(...)`
|
|
8. **All `self.service.workflow_artifact_catalog_entry(...)`** → `self.backend.workflow_artifact_catalog_entry(...)`
|
|
9. **`_live_source_diagnostics(self.service, ...)`** → `self.backend.check_source_liveness(deployment=..., artifacts=...)`
|
|
10. **`_observed_node_specs(self.service)`** → `_observed_node_specs(self.backend)` (update function signature)
|
|
11. **`_available_sources(self.service)`** → `_available_sources(self.backend)` (update function signature)
|
|
12. **`_required_capabilities_for_plan(..., service=self.service)`** → `_required_capabilities_for_plan(..., backend=self.backend)`
|
|
|
|
**Import changes** (top of file):
|
|
|
|
- Remove: `from ..broker.service.adapters import require_adapter`
|
|
- Remove: `from ..events import make_event`
|
|
- Remove: `from ..models import RawWorkflowPlan`
|
|
- Remove: `from ..shared import matches_query, paged_list_payload`
|
|
- Remove: `if TYPE_CHECKING: from ..broker.service import WfMcpService`
|
|
- Remove: `import anyio`, `import httpx`, `from mcp.client.streamable_http import StreamableHTTPError`, `from mcp.shared.exceptions import McpError`
|
|
- Remove: `LIVE_SOURCE_CHECK_TIMEOUT_SECONDS`, `_LIVE_SOURCE_CHECK_FAILURES`
|
|
- Add: `from .backend import WorkflowApiBackend`
|
|
- Add: `from .events import make_event`
|
|
- Add: `from .listing import matches_query, paged_list_payload`
|
|
- Add: `from .models import RawWorkflowPlan`
|
|
- Update all `.constants`, `.models`, `.refs`, `.next_actions`, `.saved_subgraphs`, `.run_lifecycle`, `.wrapper_hints` to `wf_api.*`
|
|
|
|
**Module-level helpers to update:**
|
|
|
|
- `_available_sources(service: WfMcpService)` → `_available_sources(backend: WorkflowApiBackend)` — change `service.capability_sources` to `backend.capability_sources`
|
|
- `_observed_node_specs(service: WfMcpService)` → `_observed_node_specs(backend: WorkflowApiBackend)` — change `service.capability_sources` to `backend.capability_sources`
|
|
- `_required_capabilities_for_plan(..., service: WfMcpService)` → `_required_capabilities_for_plan(..., backend: WorkflowApiBackend)` — change `service` references to `backend`
|
|
- **Remove** `_live_source_diagnostics` function entirely (it moves into the adapter)
|
|
- **Remove** `_required_live_sources` function (it moves into the adapter)
|
|
- **Remove** `LIVE_SOURCE_CHECK_TIMEOUT_SECONDS` and `_LIVE_SOURCE_CHECK_FAILURES` constants
|
|
|
|
**`validate_deployment` method change:**
|
|
|
|
```python
|
|
async def validate_deployment(
|
|
self,
|
|
*,
|
|
deployment_id: str,
|
|
live_check: bool = False,
|
|
) -> dict[str, Any]:
|
|
deployment, artifact, diagnostics, tree = self._deployment_validation(
|
|
deployment_id
|
|
)
|
|
if live_check:
|
|
diagnostics.extend(
|
|
await self.backend.check_source_liveness(
|
|
deployment=deployment,
|
|
artifacts=[artifact, *tree.artifacts_by_ref.values()],
|
|
)
|
|
)
|
|
# ... rest unchanged
|
|
```
|
|
|
|
- [ ] **Step 2: Verify import**
|
|
|
|
```bash
|
|
uv run python -c "from wf_api.service import WorkflowApi; print('OK')"
|
|
```
|
|
|
|
Expected: `OK`.
|
|
|
|
- [ ] **Step 3: Commit**
|
|
|
|
```bash
|
|
git add src/wf_api/service.py
|
|
git commit -m "feat(wf_api): add WorkflowApi service"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 7: Replace `handlers.py` with shim
|
|
|
|
**Files:**
|
|
|
|
- Modify: `src/wf_mcp/workflow_surface/handlers.py`
|
|
|
|
- [ ] **Step 1: Replace entire file with shim**
|
|
|
|
```python
|
|
"""Backward-compatibility shim — canonical location is wf_api.service."""
|
|
|
|
from wf_api.service import WorkflowApi as WorkflowSurfaceHandlers
|
|
|
|
__all__ = ["WorkflowSurfaceHandlers"]
|
|
```
|
|
|
|
- [ ] **Step 2: Verify all workflow surface tests pass**
|
|
|
|
```bash
|
|
uv run pytest tests/wf_mcp/workflow_surface/ -q
|
|
```
|
|
|
|
Expected: all pass. Tests import `WorkflowSurfaceHandlers` from `wf_mcp.workflow_surface` which re-exports from `wf_api.service`.
|
|
|
|
- [ ] **Step 3: Commit**
|
|
|
|
```bash
|
|
git add src/wf_mcp/workflow_surface/handlers.py
|
|
git commit -m "refactor: replace handlers.py with shim to wf_api.service"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 8: Create `WfMcpWorkflowApiBackend` adapter
|
|
|
|
**Files:**
|
|
|
|
- Create: `src/wf_mcp/broker/service/workflow_api_backend.py`
|
|
|
|
- [ ] **Step 1: Write `src/wf_mcp/broker/service/workflow_api_backend.py`**
|
|
|
|
```python
|
|
from __future__ import annotations
|
|
|
|
import asyncio
|
|
from collections.abc import Sequence
|
|
from typing import Any
|
|
|
|
import anyio
|
|
import httpx
|
|
from mcp.client.streamable_http import StreamableHTTPError
|
|
from mcp.shared.exceptions import McpError
|
|
|
|
from wf_api.backend import WorkflowApiBackend
|
|
from wf_api.events import McpEvent
|
|
from wf_artifacts import (
|
|
DependencyDiagnostic,
|
|
DiagnosticSeverity,
|
|
DraftWorkspaceStore,
|
|
RunStore,
|
|
WorkflowArtifact,
|
|
WorkflowArtifactCatalogEntry,
|
|
WorkflowArtifactStore,
|
|
WorkflowDeployment,
|
|
)
|
|
from wf_authoring import NodeSpec
|
|
from wf_platform import CapabilitySource
|
|
|
|
from .adapters import require_adapter
|
|
from .core import WfMcpService
|
|
|
|
LIVE_SOURCE_CHECK_TIMEOUT_SECONDS = 8.0
|
|
_LIVE_SOURCE_CHECK_FAILURES = (
|
|
KeyError,
|
|
TimeoutError,
|
|
OSError,
|
|
anyio.ClosedResourceError,
|
|
anyio.EndOfStream,
|
|
anyio.BrokenResourceError,
|
|
httpx.HTTPError,
|
|
McpError,
|
|
StreamableHTTPError,
|
|
)
|
|
|
|
|
|
class WfMcpWorkflowApiBackend:
|
|
"""Adapt WfMcpService into the WorkflowApiBackend protocol."""
|
|
|
|
def __init__(self, service: WfMcpService) -> None:
|
|
self._service = service
|
|
|
|
@property
|
|
def artifact_store(self) -> WorkflowArtifactStore | None:
|
|
return self._service.artifact_store
|
|
|
|
@property
|
|
def draft_workspace_store(self) -> DraftWorkspaceStore | None:
|
|
return self._service.draft_workspace_store
|
|
|
|
@property
|
|
def run_store(self) -> RunStore | None:
|
|
return self._service.run_store
|
|
|
|
@property
|
|
def capability_sources(self) -> dict[str, CapabilitySource]:
|
|
return self._service.capability_sources
|
|
|
|
def get_qualified_spec(self, qualified_name: str) -> NodeSpec[Any, Any]:
|
|
return self._service._get_qualified_spec(qualified_name)
|
|
|
|
def record_event(self, event: McpEvent) -> None:
|
|
self._service._record_event(event)
|
|
|
|
async def run_workflow_from_plan(
|
|
self,
|
|
plan: Any,
|
|
workflow_input: dict[str, Any],
|
|
*,
|
|
deployment: WorkflowDeployment | None = None,
|
|
artifact: WorkflowArtifact | None = None,
|
|
saved_subgraph_tree: Any | None = None,
|
|
) -> Any:
|
|
return await self._service.run_workflow_from_plan(
|
|
plan,
|
|
workflow_input,
|
|
deployment=deployment,
|
|
artifact=artifact,
|
|
saved_subgraph_tree=saved_subgraph_tree,
|
|
)
|
|
|
|
async def resume_workflow_from_plan(
|
|
self,
|
|
plan: Any,
|
|
run: Any,
|
|
*,
|
|
resume_payload: dict[str, Any],
|
|
resume_outcome: str = "submitted",
|
|
deployment: WorkflowDeployment | None = None,
|
|
artifact: WorkflowArtifact | None = None,
|
|
saved_subgraph_tree: Any | None = None,
|
|
) -> Any:
|
|
return await self._service.resume_workflow_from_plan(
|
|
plan,
|
|
run,
|
|
resume_payload=resume_payload,
|
|
resume_outcome=resume_outcome,
|
|
deployment=deployment,
|
|
artifact=artifact,
|
|
saved_subgraph_tree=saved_subgraph_tree,
|
|
)
|
|
|
|
def workflow_artifact_catalog_entry(
|
|
self,
|
|
artifact: WorkflowArtifact,
|
|
) -> WorkflowArtifactCatalogEntry:
|
|
return self._service.workflow_artifact_catalog_entry(artifact)
|
|
|
|
async def check_source_liveness(
|
|
self,
|
|
*,
|
|
deployment: WorkflowDeployment,
|
|
artifacts: Sequence[WorkflowArtifact],
|
|
) -> list[DependencyDiagnostic]:
|
|
return await _live_source_diagnostics(
|
|
self._service,
|
|
deployment=deployment,
|
|
artifacts=artifacts,
|
|
)
|
|
|
|
|
|
async def _live_source_diagnostics(
|
|
service: WfMcpService,
|
|
*,
|
|
deployment: WorkflowDeployment,
|
|
artifacts: Sequence[WorkflowArtifact],
|
|
) -> list[DependencyDiagnostic]:
|
|
"""MCP-specific live connectivity probe for bound upstream sources."""
|
|
diagnostics: list[DependencyDiagnostic] = []
|
|
bindings = deployment.binding_map()
|
|
required: dict[str, str] = {}
|
|
for artifact in artifacts:
|
|
for logical_ref, capability in artifact.required_capability_map().items():
|
|
source_id = bindings.get(capability.logical_source)
|
|
if source_id is not None:
|
|
required.setdefault(source_id, logical_ref)
|
|
|
|
for source_id, logical_ref in required.items():
|
|
source = service.capability_sources.get(source_id)
|
|
if (
|
|
source is None
|
|
or not source.enabled
|
|
or not source.permissions.calls_upstream
|
|
):
|
|
continue
|
|
try:
|
|
connection = service.connections.get(source_id)
|
|
adapter = require_adapter(connection, service.adapters)
|
|
auth = service.load_auth(source_id)
|
|
await asyncio.wait_for(
|
|
adapter.list_tools(connection, auth),
|
|
timeout=LIVE_SOURCE_CHECK_TIMEOUT_SECONDS,
|
|
)
|
|
except _LIVE_SOURCE_CHECK_FAILURES as exc:
|
|
diagnostics.append(
|
|
DependencyDiagnostic(
|
|
severity=DiagnosticSeverity.ERROR,
|
|
code="source_unreachable",
|
|
logical_ref=logical_ref,
|
|
bound_source=source_id,
|
|
message=(
|
|
f"Live check for upstream source {source_id!r} failed: "
|
|
f"{type(exc).__name__}: {exc}"
|
|
),
|
|
repair_hint=(
|
|
"Start or reconnect the source, fix its transport/auth "
|
|
"configuration, or bind this deployment to another source."
|
|
),
|
|
)
|
|
)
|
|
return diagnostics
|
|
```
|
|
|
|
- [ ] **Step 2: Verify import**
|
|
|
|
```bash
|
|
uv run python -c "from wf_mcp.broker.service.workflow_api_backend import WfMcpWorkflowApiBackend; print('OK')"
|
|
```
|
|
|
|
Expected: `OK`.
|
|
|
|
- [ ] **Step 3: Commit**
|
|
|
|
```bash
|
|
git add src/wf_mcp/broker/service/workflow_api_backend.py
|
|
git commit -m "feat(wf_mcp): add WfMcpWorkflowApiBackend adapter"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 9: Update MCP tool registration to use `WorkflowApi`
|
|
|
|
**Files:**
|
|
|
|
- Modify: `src/wf_mcp/workflow_surface/tools.py`
|
|
|
|
- [ ] **Step 1: Update imports in `src/wf_mcp/workflow_surface/tools.py`**
|
|
|
|
Change:
|
|
|
|
```python
|
|
from wf_mcp.broker.service import WfMcpService
|
|
from .handlers import WorkflowSurfaceHandlers
|
|
from .models import (
|
|
...,
|
|
TraceRange,
|
|
...
|
|
)
|
|
```
|
|
|
|
To:
|
|
|
|
```python
|
|
from wf_api.service import WorkflowApi
|
|
from wf_api.models import TraceRange
|
|
from wf_mcp.broker.service import WfMcpService
|
|
from wf_mcp.broker.service.workflow_api_backend import WfMcpWorkflowApiBackend
|
|
from .models import (
|
|
...,
|
|
# Remove TraceRange from this import
|
|
...
|
|
)
|
|
```
|
|
|
|
- [ ] **Step 2: Update `register_workflow_tools` function body**
|
|
|
|
Change:
|
|
|
|
```python
|
|
def register_workflow_tools(server: FastMCP[Any], service: WfMcpService) -> None:
|
|
"""Register stable workflow tools on the public MCP server surface."""
|
|
handlers = WorkflowSurfaceHandlers(service)
|
|
```
|
|
|
|
To:
|
|
|
|
```python
|
|
def register_workflow_tools(server: FastMCP[Any], service: WfMcpService) -> None:
|
|
"""Register stable workflow tools on the public MCP server surface."""
|
|
handlers = WorkflowApi(WfMcpWorkflowApiBackend(service))
|
|
```
|
|
|
|
All references to `handlers.X(...)` remain unchanged — `WorkflowApi` has the same methods.
|
|
|
|
- [ ] **Step 3: Verify all workflow surface tests pass**
|
|
|
|
```bash
|
|
uv run pytest tests/wf_mcp/workflow_surface/ -q
|
|
```
|
|
|
|
Expected: all pass.
|
|
|
|
- [ ] **Step 4: Commit**
|
|
|
|
```bash
|
|
git add src/wf_mcp/workflow_surface/tools.py
|
|
git commit -m "refactor: use WorkflowApi in MCP tool registration"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 10: Update `wf_cli.context` to use `WorkflowApi`
|
|
|
|
**Files:**
|
|
|
|
- Modify: `src/wf_cli/context.py`
|
|
|
|
- [ ] **Step 1: Update imports**
|
|
|
|
Change:
|
|
|
|
```python
|
|
from wf_mcp.workflow_surface import WorkflowSurfaceHandlers
|
|
```
|
|
|
|
To:
|
|
|
|
```python
|
|
from wf_api import WorkflowApi
|
|
from wf_mcp.broker.service.workflow_api_backend import WfMcpWorkflowApiBackend
|
|
```
|
|
|
|
- [ ] **Step 2: Update `CliContext` dataclass**
|
|
|
|
Change:
|
|
|
|
```python
|
|
@dataclass(frozen=True)
|
|
class CliContext:
|
|
config_path: Path
|
|
service: WfMcpService
|
|
handlers: WorkflowSurfaceHandlers
|
|
```
|
|
|
|
To:
|
|
|
|
```python
|
|
@dataclass(frozen=True)
|
|
class CliContext:
|
|
config_path: Path
|
|
service: WfMcpService
|
|
handlers: WorkflowApi
|
|
```
|
|
|
|
- [ ] **Step 3: Update `load_cli_context` function**
|
|
|
|
Change:
|
|
|
|
```python
|
|
def load_cli_context(config_path: str | Path) -> CliContext:
|
|
resolved_config_path = Path(config_path)
|
|
config = load_broker_config(resolved_config_path)
|
|
service = build_service_from_config(config)
|
|
return CliContext(
|
|
config_path=resolved_config_path,
|
|
service=service,
|
|
handlers=WorkflowSurfaceHandlers(service),
|
|
)
|
|
```
|
|
|
|
To:
|
|
|
|
```python
|
|
def load_cli_context(config_path: str | Path) -> CliContext:
|
|
resolved_config_path = Path(config_path)
|
|
config = load_broker_config(resolved_config_path)
|
|
service = build_service_from_config(config)
|
|
return CliContext(
|
|
config_path=resolved_config_path,
|
|
service=service,
|
|
handlers=WorkflowApi(WfMcpWorkflowApiBackend(service)),
|
|
)
|
|
```
|
|
|
|
- [ ] **Step 4: Update `src/wf_cli/commands/runs.py`**
|
|
|
|
Change:
|
|
|
|
```python
|
|
from wf_mcp.workflow_surface import TraceRange
|
|
```
|
|
|
|
To:
|
|
|
|
```python
|
|
from wf_api.models import TraceRange
|
|
```
|
|
|
|
- [ ] **Step 5: Verify CLI tests pass**
|
|
|
|
```bash
|
|
uv run pytest tests/wf_cli/ -q
|
|
```
|
|
|
|
Expected: all pass.
|
|
|
|
- [ ] **Step 6: Commit**
|
|
|
|
```bash
|
|
git add src/wf_cli/context.py src/wf_cli/commands/runs.py
|
|
git commit -m "refactor: use WorkflowApi in CLI context"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 11: Add `wf_api` to `pyproject.toml` packages
|
|
|
|
**Files:**
|
|
|
|
- Modify: `pyproject.toml`
|
|
|
|
- [ ] **Step 1: Find the packages list in `pyproject.toml`**
|
|
|
|
Grep for `packages` or `find` in the `[tool.setuptools]` or `[tool.hatch]` section.
|
|
|
|
- [ ] **Step 2: Add `src/wf_api` to the packages list**
|
|
|
|
If using `find`:
|
|
|
|
```toml
|
|
[tool.setuptools.packages.find]
|
|
where = ["src"]
|
|
```
|
|
|
|
This should auto-discover `wf_api`. If packages are listed explicitly, add `"wf_api"`.
|
|
|
|
- [ ] **Step 3: Verify package is importable**
|
|
|
|
```bash
|
|
uv run python -c "from wf_api import WorkflowApi, WorkflowApiBackend; print('OK')"
|
|
```
|
|
|
|
Expected: `OK`.
|
|
|
|
- [ ] **Step 4: Commit**
|
|
|
|
```bash
|
|
git add pyproject.toml
|
|
git commit -m "build: add wf_api to package discovery"
|
|
```
|
|
|
|
---
|
|
|
|
## Task 12: Full test suite verification
|
|
|
|
- [ ] **Step 1: Run all workflow surface tests**
|
|
|
|
```bash
|
|
uv run pytest tests/wf_mcp/workflow_surface/ -q
|
|
```
|
|
|
|
Expected: all pass.
|
|
|
|
- [ ] **Step 2: Run all CLI tests**
|
|
|
|
```bash
|
|
uv run pytest tests/wf_cli/ -q
|
|
```
|
|
|
|
Expected: all pass.
|
|
|
|
- [ ] **Step 3: Run all MCP tests**
|
|
|
|
```bash
|
|
uv run pytest tests/wf_mcp/ -q
|
|
```
|
|
|
|
Expected: all pass.
|
|
|
|
- [ ] **Step 4: Run full test suite**
|
|
|
|
```bash
|
|
uv run pytest -q
|
|
```
|
|
|
|
Expected: all pass.
|
|
|
|
- [ ] **Step 5: Verify import direction rule**
|
|
|
|
```bash
|
|
uv run python -c "
|
|
import ast, sys
|
|
|
|
violations = []
|
|
for mod in ['wf_api.service', 'wf_api.backend', 'wf_api.events', 'wf_api.listing',
|
|
'wf_api.models', 'wf_api.constants', 'wf_api.refs', 'wf_api.next_actions',
|
|
'wf_api.wrapper_hints', 'wf_api.runtime_dependencies', 'wf_api.saved_subgraphs',
|
|
'wf_api.run_lifecycle']:
|
|
try:
|
|
file_path = mod.replace('.', '/') + '.py'
|
|
with open(file_path) as f:
|
|
tree = ast.parse(f.read())
|
|
for node in ast.walk(tree):
|
|
if isinstance(node, ast.ImportFrom) and node.module and node.module.startswith('wf_mcp'):
|
|
violations.append(f'{mod}: from {node.module} import ...')
|
|
except FileNotFoundError:
|
|
pass
|
|
|
|
if violations:
|
|
print('VIOLATIONS:')
|
|
for v in violations:
|
|
print(f' {v}')
|
|
sys.exit(1)
|
|
else:
|
|
print('OK: wf_api has no wf_mcp imports')
|
|
"
|
|
```
|
|
|
|
Expected: `OK: wf_api has no wf_mcp imports`.
|
|
|
|
- [ ] **Step 6: Run lint/typecheck**
|
|
|
|
```bash
|
|
uv run ruff check src/wf_api/ src/wf_mcp/workflow_surface/ src/wf_cli/context.py src/wf_mcp/broker/service/workflow_api_backend.py
|
|
uv run basedpyright --level error
|
|
```
|
|
|
|
Expected: no new errors.
|
|
|
|
---
|
|
|
|
## Task 13: Final commit — all changes
|
|
|
|
- [ ] **Step 1: Verify clean working tree**
|
|
|
|
```bash
|
|
git status
|
|
```
|
|
|
|
Expected: no uncommitted changes (all tasks committed individually).
|
|
|
|
- [ ] **Step 2: Verify commit log**
|
|
|
|
```bash
|
|
git log --oneline -15
|
|
```
|
|
|
|
Expected: all task commits visible.
|
|
|
|
---
|
|
|
|
## Rollback / Compatibility Notes
|
|
|
|
1. **Shim-based rollback:** Every moved module has a shim in its original location. To rollback, replace each shim with the original file content and delete the `wf_api/` package.
|
|
|
|
2. **`CliContext.handlers` attribute name preserved:** All CLI command code uses `context.handlers.X()`. The attribute name `handlers` is unchanged; only the type changes from `WorkflowSurfaceHandlers` to `WorkflowApi`.
|
|
|
|
3. **`wf_mcp.workflow_surface.__init__.py` re-exports preserved:** `from wf_mcp.workflow_surface import WorkflowSurfaceHandlers` still works via the `handlers.py` shim. Same for `TraceRange`.
|
|
|
|
4. **Test monkeypatch paths preserved:** Tests that `patch("wf_cli.commands.runs.load_cli_context", ...)` still work because `load_cli_context` is still the function being patched. The patched function constructs `WorkflowApi` instead of `WorkflowSurfaceHandlers`, but the mock replaces the whole function.
|
|
|
|
5. **`WfMcpService` unchanged:** The `WfMcpService` class itself is not modified. The adapter wraps it without changing its behavior.
|
|
|
|
6. **`live_check` behavior preserved:** `validate_deployment(live_check=True)` calls `self.backend.check_source_liveness(...)`. The MCP adapter implements this with the same `_live_source_diagnostics` logic (connections, adapters, auth probe). Non-MCP backends can return an empty list or implement their own liveness checks.
|
|
|
|
7. **Event naming unchanged:** `McpEvent` keeps its name. Renaming to `DomainEvent` is a Slice 2 concern.
|
|
|
|
---
|
|
|
|
## Verification Commands Summary
|
|
|
|
```bash
|
|
# Per-task verification
|
|
uv run pytest tests/wf_mcp/workflow_surface/ -q
|
|
uv run pytest tests/wf_cli/ -q
|
|
uv run pytest tests/wf_mcp/ -q
|
|
|
|
# Full suite
|
|
uv run pytest -q
|
|
|
|
# Import direction check
|
|
uv run python -c "
|
|
import ast, sys
|
|
violations = []
|
|
for mod in ['wf_api.service', 'wf_api.backend', 'wf_api.events', 'wf_api.listing',
|
|
'wf_api.models', 'wf_api.constants', 'wf_api.refs', 'wf_api.next_actions',
|
|
'wf_api.wrapper_hints', 'wf_api.runtime_dependencies', 'wf_api.saved_subgraphs',
|
|
'wf_api.run_lifecycle']:
|
|
try:
|
|
file_path = mod.replace('.', '/') + '.py'
|
|
with open(file_path) as f:
|
|
tree = ast.parse(f.read())
|
|
for node in ast.walk(tree):
|
|
if isinstance(node, ast.ImportFrom) and node.module and node.module.startswith('wf_mcp'):
|
|
violations.append(f'{mod}: from {node.module} import ...')
|
|
except FileNotFoundError:
|
|
pass
|
|
if violations:
|
|
print('VIOLATIONS:'); [print(f' {v}') for v in violations]; sys.exit(1)
|
|
else:
|
|
print('OK: wf_api has no wf_mcp imports')
|
|
"
|
|
|
|
# Lint
|
|
uv run ruff check src/wf_api/
|
|
uv run basedpyright --level error
|
|
```
|