630 lines
20 KiB
Markdown
630 lines
20 KiB
Markdown
# Next Actions Model Refactor Implementation Plan
|
|
|
|
> **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:** Move MCP workflow guidance UX into reusable `NextActions` models so wrapper draft guidance stops living as ad-hoc dict helpers in `handlers.py`.
|
|
|
|
**Architecture:** Add `src/wf_mcp/workflow_surface/next_actions.py` as the single owner of next-action enums, response models, and the first constructor: `NextActions.from_wrapper_hints(...)`. Keep the existing `create_draft_workspace_from_capability` JSON stable, with `can_continue` as the only additive field. Do not add deployment/run guidance in this pass; this is the foundation for those later constructors.
|
|
|
|
**Tech Stack:** Python 3.14, Pydantic v2, FastMCP schema generation, pytest, ruff, basedpyright.
|
|
|
|
---
|
|
|
|
## File Structure
|
|
|
|
- Create `src/wf_mcp/workflow_surface/next_actions.py`
|
|
- Owns `NextActionTool`, `NextActionPatchExample`, and `NextActions`.
|
|
- Owns wrapper-hint guidance policy currently in `handlers.py`.
|
|
- Contains docstrings explaining that `next_actions` is advisory, not authority.
|
|
|
|
- Modify `src/wf_mcp/workflow_surface/models.py`
|
|
- Reuse the generic models for MCP response schemas.
|
|
- Keep compatibility aliases for `WrapperDraftPatchExample` and `WrapperDraftNextActions` if local imports or generated schemas still reference the old names.
|
|
|
|
- Modify `src/wf_mcp/workflow_surface/handlers.py`
|
|
- Remove `_wrapper_draft_next_actions(...)` and `_wrapper_draft_patch_examples(...)`.
|
|
- Call `NextActions.from_wrapper_hints(...).model_dump(mode="json")`.
|
|
|
|
- Create `tests/wf_mcp/workflow_surface/test_next_actions.py`
|
|
- Unit-test the generic model without the full draft store.
|
|
|
|
- Modify `tests/wf_mcp/workflow_surface/test_drafts.py`
|
|
- Keep integration coverage through `create_draft_workspace_from_capability`.
|
|
- Assert old fields still exist and `can_continue` is additive.
|
|
|
|
- Modify `tests/wf_mcp/server/test_config.py`
|
|
- Assert the MCP output schema documents `can_continue` and still documents `can_save_now`.
|
|
|
|
- Modify `docs/workflow_capabilities.md`
|
|
- Add one short note that `next_actions` is advisory guidance and not validation authority.
|
|
|
|
## Scope Boundaries
|
|
|
|
- Do not add `NextActions.from_deployment_validation(...)` in this pass.
|
|
- Do not add `NextActions.from_run_result(...)` in this pass.
|
|
- Do not change current wrapper patch example semantics.
|
|
- Do not infer MCP content block extraction or boolean routing.
|
|
- Do not make `can_save_now` authoritative.
|
|
|
|
---
|
|
|
|
### Task 1: Add Generic Next-Actions Unit Tests
|
|
|
|
**Files:**
|
|
|
|
- Create: `tests/wf_mcp/workflow_surface/test_next_actions.py`
|
|
|
|
- [ ] **Step 1: Write failing tests for high-confidence wrapper hints**
|
|
|
|
Create `tests/wf_mcp/workflow_surface/test_next_actions.py`:
|
|
|
|
```python
|
|
from __future__ import annotations
|
|
|
|
from wf_mcp.workflow_surface.next_actions import NextActionTool, NextActions
|
|
|
|
|
|
def test_next_actions_from_high_confidence_wrapper_hints_can_validate() -> None:
|
|
actions = NextActions.from_wrapper_hints(
|
|
workspace_id="echo_workspace",
|
|
revision=3,
|
|
hints={
|
|
"confidence": "high",
|
|
"missing_decisions": [],
|
|
"notes": [],
|
|
},
|
|
)
|
|
|
|
dumped = actions.model_dump(mode="json")
|
|
assert dumped["can_continue"] is True
|
|
assert dumped["can_save_now"] is True
|
|
assert dumped["recommended_next_tool"] == (
|
|
NextActionTool.VALIDATE_DRAFT_WORKSPACE.value
|
|
)
|
|
assert "high confidence" in dumped["reason"]
|
|
assert dumped["patch_examples"] == []
|
|
assert dumped["warnings"] == []
|
|
```
|
|
|
|
- [ ] **Step 2: Write failing tests for low-confidence wrapper hints**
|
|
|
|
Append to `tests/wf_mcp/workflow_surface/test_next_actions.py`:
|
|
|
|
```python
|
|
def test_next_actions_from_low_confidence_wrapper_hints_can_patch() -> None:
|
|
actions = NextActions.from_wrapper_hints(
|
|
workspace_id="echo_workspace",
|
|
revision=4,
|
|
hints={
|
|
"confidence": "low",
|
|
"missing_decisions": [
|
|
{
|
|
"kind": "review_nested_output",
|
|
"message": "Review nested output fields before mapping.",
|
|
},
|
|
{
|
|
"kind": "confirm_boolean_outcomes",
|
|
"message": "Boolean fields may be data, not outcomes.",
|
|
},
|
|
],
|
|
"notes": ["Raw MCP tool output is not workflow-shaped."],
|
|
},
|
|
)
|
|
|
|
dumped = actions.model_dump(mode="json")
|
|
assert dumped["can_continue"] is True
|
|
assert dumped["can_save_now"] is False
|
|
assert dumped["recommended_next_tool"] == NextActionTool.PATCH_DRAFT_WORKSPACE.value
|
|
assert "missing wrapper decisions" in dumped["reason"]
|
|
assert dumped["warnings"][0] == "Raw MCP tool output is not workflow-shaped."
|
|
assert len(dumped["patch_examples"]) == 2
|
|
assert dumped["patch_examples"][0]["tool"] == (
|
|
NextActionTool.PATCH_DRAFT_WORKSPACE.value
|
|
)
|
|
assert dumped["patch_examples"][0]["request"]["workspace_id"] == "echo_workspace"
|
|
assert dumped["patch_examples"][0]["request"]["revision"] == 4
|
|
assert dumped["patch_examples"][0]["request"]["patch"][0]["path"] == (
|
|
"/draft/steps/call/output"
|
|
)
|
|
assert dumped["patch_examples"][1]["request"]["patch"] == []
|
|
```
|
|
|
|
- [ ] **Step 3: Run the focused test to verify it fails**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
uv run pytest tests/wf_mcp/workflow_surface/test_next_actions.py -q
|
|
```
|
|
|
|
Expected: FAIL with `ModuleNotFoundError: No module named 'wf_mcp.workflow_surface.next_actions'`.
|
|
|
|
---
|
|
|
|
### Task 2: Implement `next_actions.py`
|
|
|
|
**Files:**
|
|
|
|
- Create: `src/wf_mcp/workflow_surface/next_actions.py`
|
|
|
|
- [ ] **Step 1: Create the generic models and wrapper-hints constructor**
|
|
|
|
Create `src/wf_mcp/workflow_surface/next_actions.py`:
|
|
|
|
```python
|
|
from __future__ import annotations
|
|
|
|
from enum import StrEnum
|
|
from typing import Any, Self
|
|
|
|
from pydantic import BaseModel, Field
|
|
|
|
from .wrapper_hints import WrapperAuthoringHints
|
|
|
|
|
|
class NextActionTool(StrEnum):
|
|
"""Stable MCP workflow tools that guidance may recommend."""
|
|
|
|
PATCH_DRAFT_WORKSPACE = "wf.workflow.patch_draft_workspace"
|
|
VALIDATE_DRAFT_WORKSPACE = "wf.workflow.validate_draft_workspace"
|
|
VALIDATE_DEPLOYMENT = "wf.workflow.validate_deployment"
|
|
RUN_DEPLOYMENT = "wf.workflow.run_deployment"
|
|
RESUME_RUN = "wf.workflow.resume_run"
|
|
READ_RUN_TRACE = "wf.workflow.read_run_trace"
|
|
|
|
|
|
class NextActionPatchExample(BaseModel):
|
|
"""Concrete example request for a recommended MCP workflow tool."""
|
|
|
|
description: str = Field(description="Human-readable reason for this example.")
|
|
tool: NextActionTool = Field(description="MCP workflow tool to call.")
|
|
request: dict[str, Any] = Field(
|
|
description="JSON request payload to pass to the tool."
|
|
)
|
|
|
|
|
|
class NextActions(BaseModel):
|
|
"""Advisory continuation hints for MCP workflow clients.
|
|
|
|
This object is guidance, not authority. Validation diagnostics and runtime
|
|
status remain the source of truth; clients should treat this as a compact
|
|
answer to "what tool should I call next?"
|
|
"""
|
|
|
|
can_continue: bool = Field(
|
|
description=(
|
|
"Whether there is an obvious next workflow-surface tool call. "
|
|
"Advisory only."
|
|
)
|
|
)
|
|
can_save_now: bool | None = Field(
|
|
default=None,
|
|
description=(
|
|
"Advisory wrapper-authoring signal. False means review is "
|
|
"recommended before saving; the server does not enforce this."
|
|
),
|
|
)
|
|
recommended_next_tool: NextActionTool | None = Field(
|
|
default=None,
|
|
description="Suggested next MCP workflow tool, if one is obvious.",
|
|
)
|
|
reason: str = Field(description="Short explanation for the recommendation.")
|
|
patch_examples: list[NextActionPatchExample] = Field(
|
|
default_factory=list,
|
|
description="Concrete JSON Patch examples for common missing decisions.",
|
|
)
|
|
warnings: list[str] = Field(
|
|
default_factory=list,
|
|
description="Non-blocking warnings copied from low-confidence hints.",
|
|
)
|
|
|
|
@classmethod
|
|
def from_wrapper_hints(
|
|
cls,
|
|
*,
|
|
workspace_id: str,
|
|
revision: int,
|
|
hints: WrapperAuthoringHints | dict[str, Any],
|
|
) -> Self:
|
|
"""Create guidance after bootstrapping a wrapper draft workspace."""
|
|
payload = (
|
|
hints.model_dump(mode="json") if isinstance(hints, WrapperAuthoringHints)
|
|
else hints
|
|
)
|
|
confidence = str(payload.get("confidence", "low"))
|
|
missing_decisions = payload.get("missing_decisions")
|
|
notes = [
|
|
str(note) for note in payload.get("notes", []) if isinstance(note, str)
|
|
]
|
|
has_missing = (
|
|
isinstance(missing_decisions, list) and len(missing_decisions) > 0
|
|
)
|
|
can_save_now = confidence == "high" and not has_missing
|
|
if can_save_now:
|
|
return cls(
|
|
can_continue=True,
|
|
can_save_now=True,
|
|
recommended_next_tool=NextActionTool.VALIDATE_DRAFT_WORKSPACE,
|
|
reason="Wrapper hints are high confidence and have no missing decisions.",
|
|
patch_examples=[],
|
|
warnings=[],
|
|
)
|
|
|
|
return cls(
|
|
can_continue=True,
|
|
can_save_now=False,
|
|
recommended_next_tool=NextActionTool.PATCH_DRAFT_WORKSPACE,
|
|
reason="Review missing wrapper decisions before saving.",
|
|
patch_examples=_wrapper_draft_patch_examples(
|
|
workspace_id=workspace_id,
|
|
revision=revision,
|
|
hints=payload,
|
|
),
|
|
warnings=notes,
|
|
)
|
|
|
|
|
|
def _wrapper_draft_patch_examples(
|
|
*,
|
|
workspace_id: str,
|
|
revision: int,
|
|
hints: dict[str, Any],
|
|
) -> list[NextActionPatchExample]:
|
|
"""Return conservative JSON Patch examples without guessing semantics."""
|
|
examples: list[NextActionPatchExample] = []
|
|
missing_decisions = hints.get("missing_decisions")
|
|
if not isinstance(missing_decisions, list):
|
|
return examples
|
|
decision_kinds = {
|
|
str(decision.get("kind"))
|
|
for decision in missing_decisions
|
|
if isinstance(decision, dict)
|
|
}
|
|
if {"choose_output_fields", "review_nested_output"} & decision_kinds:
|
|
examples.append(
|
|
NextActionPatchExample(
|
|
description=(
|
|
"Replace output bindings after choosing which capability "
|
|
"outputs should be written to workflow state."
|
|
),
|
|
tool=NextActionTool.PATCH_DRAFT_WORKSPACE,
|
|
request={
|
|
"workspace_id": workspace_id,
|
|
"revision": revision,
|
|
"patch": [
|
|
{
|
|
"op": "replace",
|
|
"path": "/draft/steps/call/output",
|
|
"value": [],
|
|
}
|
|
],
|
|
},
|
|
)
|
|
)
|
|
if "confirm_boolean_outcomes" in decision_kinds:
|
|
examples.append(
|
|
NextActionPatchExample(
|
|
description=(
|
|
"Review boolean output candidates before adding routing; "
|
|
"do not route on boolean fields automatically."
|
|
),
|
|
tool=NextActionTool.PATCH_DRAFT_WORKSPACE,
|
|
request={
|
|
"workspace_id": workspace_id,
|
|
"revision": revision,
|
|
"patch": [],
|
|
},
|
|
)
|
|
)
|
|
return examples
|
|
```
|
|
|
|
- [ ] **Step 2: Run the focused unit test**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
uv run pytest tests/wf_mcp/workflow_surface/test_next_actions.py -q
|
|
```
|
|
|
|
Expected: PASS.
|
|
|
|
---
|
|
|
|
### Task 3: Replace Wrapper-Specific MCP Models with Generic Models
|
|
|
|
**Files:**
|
|
|
|
- Modify: `src/wf_mcp/workflow_surface/models.py`
|
|
|
|
- [ ] **Step 1: Import generic next-action models**
|
|
|
|
Near the other local imports in `src/wf_mcp/workflow_surface/models.py`, add:
|
|
|
|
```python
|
|
from .next_actions import NextActionPatchExample, NextActions
|
|
```
|
|
|
|
- [ ] **Step 2: Remove wrapper-specific model class bodies**
|
|
|
|
Delete the current `WrapperDraftPatchExample` and `WrapperDraftNextActions` class definitions.
|
|
|
|
Replace them with compatibility aliases immediately before `CreateDraftWorkspaceFromCapabilityResult`:
|
|
|
|
```python
|
|
# Compatibility aliases for older imports. The JSON fields are now generic
|
|
# workflow-surface guidance, not wrapper-only policy.
|
|
WrapperDraftPatchExample = NextActionPatchExample
|
|
WrapperDraftNextActions = NextActions
|
|
```
|
|
|
|
- [ ] **Step 3: Keep `CreateDraftWorkspaceFromCapabilityResult` typed with the alias**
|
|
|
|
Leave the field shape unchanged except that the alias now points at the generic type:
|
|
|
|
```python
|
|
class CreateDraftWorkspaceFromCapabilityResult(DraftWorkspaceResult):
|
|
"""Draft workspace result plus wrapper hints and advisory next actions."""
|
|
|
|
wrapper_hints: dict[str, Any] = Field(
|
|
description=(
|
|
"The wrapper_hints payload used before applying request overrides. "
|
|
"Use this to patch uncertain maps or schemas by revision."
|
|
)
|
|
)
|
|
next_actions: WrapperDraftNextActions = Field(
|
|
description=(
|
|
"Advisory next step guidance derived from wrapper_hints. "
|
|
"The server does not enforce can_save_now."
|
|
)
|
|
)
|
|
```
|
|
|
|
- [ ] **Step 4: Run model import check**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
uv run python -c "from wf_mcp.workflow_surface.models import WrapperDraftNextActions, CreateDraftWorkspaceFromCapabilityResult; print(WrapperDraftNextActions.__name__)"
|
|
```
|
|
|
|
Expected output includes:
|
|
|
|
```text
|
|
NextActions
|
|
```
|
|
|
|
---
|
|
|
|
### Task 4: Replace Handler Dict Helpers with `NextActions`
|
|
|
|
**Files:**
|
|
|
|
- Modify: `src/wf_mcp/workflow_surface/handlers.py`
|
|
|
|
- [ ] **Step 1: Import `NextActions`**
|
|
|
|
Add to the local imports in `src/wf_mcp/workflow_surface/handlers.py`:
|
|
|
|
```python
|
|
from .next_actions import NextActions
|
|
```
|
|
|
|
- [ ] **Step 2: Update `create_draft_workspace_from_capability`**
|
|
|
|
Replace the `next_actions` part of the return value with:
|
|
|
|
```python
|
|
return {
|
|
**result,
|
|
"wrapper_hints": hints,
|
|
"next_actions": NextActions.from_wrapper_hints(
|
|
workspace_id=workspace_id,
|
|
revision=int(result["revision"]),
|
|
hints=hints,
|
|
).model_dump(mode="json"),
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 3: Delete handler-local guidance helpers**
|
|
|
|
Delete these functions from `src/wf_mcp/workflow_surface/handlers.py`:
|
|
|
|
```python
|
|
def _wrapper_draft_next_actions(...)
|
|
def _wrapper_draft_patch_examples(...)
|
|
```
|
|
|
|
Do not delete `_source_id_for_capability(...)`, which follows those helpers.
|
|
|
|
- [ ] **Step 4: Run focused draft tests**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
uv run pytest tests/wf_mcp/workflow_surface/test_next_actions.py tests/wf_mcp/workflow_surface/test_drafts.py -q
|
|
```
|
|
|
|
Expected: PASS except for assertions that still need additive `can_continue` checks in Task 5.
|
|
|
|
---
|
|
|
|
### Task 5: Update Integration and Schema Tests
|
|
|
|
**Files:**
|
|
|
|
- Modify: `tests/wf_mcp/workflow_surface/test_drafts.py`
|
|
- Modify: `tests/wf_mcp/server/test_config.py`
|
|
|
|
- [ ] **Step 1: Add `can_continue` assertions to draft integration tests**
|
|
|
|
In `tests/wf_mcp/workflow_surface/test_drafts.py`, find the test that asserts high-confidence `next_actions`.
|
|
|
|
Add this assertion near the other `next_actions` assertions:
|
|
|
|
```python
|
|
assert next_actions["can_continue"] is True
|
|
```
|
|
|
|
Keep these existing assertions:
|
|
|
|
```python
|
|
assert next_actions["can_save_now"] is True
|
|
assert next_actions["recommended_next_tool"] == (
|
|
"wf.workflow.validate_draft_workspace"
|
|
)
|
|
assert "high confidence" in next_actions["reason"]
|
|
assert next_actions["patch_examples"] == []
|
|
assert next_actions["warnings"] == []
|
|
```
|
|
|
|
- [ ] **Step 2: Add `can_continue` assertion to low-confidence integration test**
|
|
|
|
In the low-confidence/content-block test in `tests/wf_mcp/workflow_surface/test_drafts.py`, add:
|
|
|
|
```python
|
|
assert next_actions["can_continue"] is True
|
|
```
|
|
|
|
Keep field-level assertions. Do not assert whole dict equality.
|
|
|
|
- [ ] **Step 3: Update MCP schema test**
|
|
|
|
In `tests/wf_mcp/server/test_config.py`, find the `create_draft_workspace_from_capability` output schema test.
|
|
|
|
Add:
|
|
|
|
```python
|
|
next_actions_schema = result_schema["properties"]["next_actions"]
|
|
next_action_properties = next_actions_schema["properties"]
|
|
assert "can_continue" in next_action_properties
|
|
assert "Advisory" in next_action_properties["can_continue"]["description"]
|
|
assert "can_save_now" in next_action_properties
|
|
assert "Advisory" in next_action_properties["can_save_now"]["description"]
|
|
```
|
|
|
|
If the existing test already has `next_actions_schema`, reuse it. Do not assert the entire generated schema.
|
|
|
|
- [ ] **Step 4: Run focused tests**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
uv run pytest tests/wf_mcp/workflow_surface/test_next_actions.py tests/wf_mcp/workflow_surface/test_drafts.py tests/wf_mcp/server/test_config.py -q
|
|
```
|
|
|
|
Expected: PASS.
|
|
|
|
---
|
|
|
|
### Task 6: Add a Small Documentation Note
|
|
|
|
**Files:**
|
|
|
|
- Modify: `docs/workflow_capabilities.md`
|
|
|
|
- [ ] **Step 1: Add an advisory-guidance note**
|
|
|
|
Find the section that mentions `next_actions` or wrapper draft guidance. Add this paragraph:
|
|
|
|
```markdown
|
|
`next_actions` is advisory guidance, not validation authority. It gives MCP
|
|
clients a compact "what should I call next?" pointer, while diagnostics,
|
|
artifact validation, deployment validation, and runtime status remain the
|
|
source of truth.
|
|
```
|
|
|
|
- [ ] **Step 2: Verify docs reference still works**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
uv run pytest tests/wf_mcp/server/test_docs.py -q
|
|
```
|
|
|
|
Expected: PASS.
|
|
|
|
---
|
|
|
|
### Task 7: Full Verification
|
|
|
|
**Files:**
|
|
|
|
- All touched files.
|
|
|
|
- [ ] **Step 1: Run focused tests**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
uv run pytest tests/wf_mcp/workflow_surface/test_next_actions.py tests/wf_mcp/workflow_surface/test_drafts.py tests/wf_mcp/server/test_config.py tests/wf_mcp/server/test_docs.py -q
|
|
```
|
|
|
|
Expected: PASS.
|
|
|
|
- [ ] **Step 2: Run formatting check on touched files**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
uv run ruff format --check src/wf_mcp/workflow_surface/next_actions.py src/wf_mcp/workflow_surface/models.py src/wf_mcp/workflow_surface/handlers.py tests/wf_mcp/workflow_surface/test_next_actions.py tests/wf_mcp/workflow_surface/test_drafts.py tests/wf_mcp/server/test_config.py
|
|
```
|
|
|
|
Expected: PASS.
|
|
|
|
- [ ] **Step 3: Run lint on touched files**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
uv run ruff check src/wf_mcp/workflow_surface/next_actions.py src/wf_mcp/workflow_surface/models.py src/wf_mcp/workflow_surface/handlers.py tests/wf_mcp/workflow_surface/test_next_actions.py tests/wf_mcp/workflow_surface/test_drafts.py tests/wf_mcp/server/test_config.py
|
|
```
|
|
|
|
Expected: PASS.
|
|
|
|
- [ ] **Step 4: Run type check**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
uv run basedpyright --level error
|
|
```
|
|
|
|
Expected: `0 errors`.
|
|
|
|
- [ ] **Step 5: Run the full test suite if time allows**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
uv run pytest -q
|
|
```
|
|
|
|
Expected: current suite status should remain unchanged from the baseline, currently about `723 passed, 1 skipped, 1 xfailed`.
|
|
|
|
---
|
|
|
|
## Self-Review Checklist
|
|
|
|
- Spec coverage:
|
|
- `next_actions.py` is created.
|
|
- Generic models exist.
|
|
- Wrapper-hint constructor exists.
|
|
- Handler-local dict helpers are removed.
|
|
- Existing JSON fields remain stable.
|
|
- Deployment/run guidance is intentionally deferred.
|
|
|
|
- Placeholder scan:
|
|
- No `TBD`.
|
|
- No open-ended "add appropriate validation".
|
|
- Each code step includes exact snippets.
|
|
|
|
- Type consistency:
|
|
- `NextActionTool.PATCH_DRAFT_WORKSPACE.value` serializes to the existing string.
|
|
- `WrapperDraftNextActions` remains importable as an alias.
|
|
- `CreateDraftWorkspaceFromCapabilityResult.next_actions` keeps the same public response location.
|
|
|
|
## Handoff Notes
|
|
|
|
This plan is intentionally small. It should not change workflow behavior or draft semantics. If any test fails outside `next_actions` schema/serialization, stop and inspect before broadening the change.
|