docs: archive completed superpowers plans

2026-06-04 22:29:32 +07:00
parent e001b524d6
commit 0d34174a84
93 changed files with 88 additions and 10 deletions
@@ -0,0 +1,574 @@
+# wf_api Slice 4D: Run Lifecycle 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 deployment run, resume, stopped-run inspection, and bounded trace reading out of `WorkflowSurfaceHandlers` into a protocol-neutral `wf_api.runs.WorkflowRunApi`.
+
+**Architecture:** `WorkflowRunApi` depends on `WorkflowOperationContext` and `WorkflowDeploymentApi`, not `WfMcpService`. Runtime execution remains adapter-owned through `WorkflowRuntimeRunner`; run persistence and payload shaping move into `wf_api`. Keep MCP Pydantic request models at the MCP boundary and pass only a structural trace range into `wf_api`.
+
+**Tech Stack:** Python 3.14+, `wf_api.operation_context`, `wf_api.deployments`, `wf_api.run_lifecycle`, `wf_api.saved_subgraphs`, `wf_artifacts` run store models, `wf_core.RunState`, pytest, ruff, basedpyright.
+
+---
+
+## Scope
+
+### Move In This Slice
+
+Move these methods from `WorkflowSurfaceHandlers` to `wf_api.runs.WorkflowRunApi`:
+
+```text
+run_deployment
+resume_run
+inspect_run
+read_run_trace
+```
+
+Move or duplicate only the helpers needed by those methods:
+
+```text
+_run_store
+_raw_plan_from_artifact
+_plan_field
+_run_payload
+_interrupt_payload
+```
+
+### Do Not Move In This Slice
+
+Do not move:
+
+```text
+list_capabilities
+inspect_capability
+call_capability
+_wrapper_artifact_for_capability_name
+_wrapper_capability_summaries
+_wrapper_capability_detail
+_call_wrapper_artifact
+```
+
+Reasons:
+
+- Capability methods still own wrapper discovery and direct test calls.
+- `_raw_plan_from_artifact` is still needed by wrapper direct calls in `handlers.py`; duplicate it temporarily in `wf_api.runs` or move it to a small shared `wf_api` helper only if that does not widen the slice.
+
+### Invariants
+
+- No public payload changes.
+- No MCP tool schema changes.
+- `WorkflowSurfaceHandlers` public run method signatures stay unchanged.
+- `wf_api` imports no `wf_mcp`.
+- Runtime event construction remains adapter-owned in `WfMcpService`.
+- `run_deployment` still persists stopped runs.
+- `resume_run` still revalidates pinned dependency environments before mutating state.
+- Trace payloads remain opt-in and bounded by `trace_range`.
+
+---
+
+## Task 1: Align Runtime Protocol With Actual Runtime Calls
+
+**Files:**
+
+- Modify: `src/wf_api/operation_context.py`
+- Modify: `src/wf_mcp/broker/service/workflow_operation_context.py`
+- Test: `tests/wf_api/test_operation_context.py`
+
+- [ ] **Step 1: Update `WorkflowRuntimeRunner` protocol**
+
+In `src/wf_api/operation_context.py`, replace the older generic runtime kwargs with the current deployment-aware shape:
+
+```python
+from wf_api.saved_subgraphs import SavedSubgraphTree
+```
+
+```python
+class WorkflowRuntimeRunner(Protocol):
+    """Runs and resumes workflow plans using an adapter-owned runtime backend."""
+
+    async def run_workflow_from_plan(
+        self,
+        plan: RawWorkflowPlan,
+        workflow_input: dict[str, Any],
+        deployment: WorkflowDeployment | None = None,
+        artifact: WorkflowArtifact | None = None,
+        saved_subgraph_tree: SavedSubgraphTree | None = None,
+    ) -> RunState:
+        """Execute one raw workflow plan and return its run state."""
+        ...
+
+    async def resume_workflow_from_plan(
+        self,
+        plan: RawWorkflowPlan,
+        run: RunState,
+        *,
+        resume_payload: dict[str, Any],
+        resume_outcome: str,
+        deployment: WorkflowDeployment | None = None,
+        artifact: WorkflowArtifact | None = None,
+        saved_subgraph_tree: SavedSubgraphTree | None = None,
+    ) -> RunState:
+        """Resume one interrupted raw workflow plan and return its run state."""
+        ...
+```
+
+Remove unused imports from the protocol file if `AsyncRegistryHandler` or
+`ReducerDefinition` are no longer needed.
+
+- [ ] **Step 2: Give adapter methods explicit signatures**
+
+In `src/wf_mcp/broker/service/workflow_operation_context.py`, replace `**kwargs`
+runtime adapter methods with explicit signatures matching the protocol:
+
+```python
+async def run_workflow_from_plan(
+    self,
+    plan,
+    workflow_input,
+    deployment=None,
+    artifact=None,
+    saved_subgraph_tree=None,
+):
+    return await self.service.run_workflow_from_plan(
+        plan,
+        workflow_input,
+        deployment=deployment,
+        artifact=artifact,
+        saved_subgraph_tree=saved_subgraph_tree,
+    )
+```
+
+Do the same for `resume_workflow_from_plan(...)`.
+
+- [ ] **Step 3: Run operation-context tests**
+
+```powershell
+uv run pytest tests/wf_api/test_operation_context.py -q
+```
+
+Expected: pass.
+
+---
+
+## Task 2: Create `wf_api.runs`
+
+**Files:**
+
+- Create: `src/wf_api/runs.py`
+- Modify: `src/wf_api/__init__.py`
+- Test: `tests/wf_api/test_run_api.py`
+
+- [ ] **Step 1: Create service skeleton and trace range protocol**
+
+Create `src/wf_api/runs.py`:
+
+```python
+from __future__ import annotations
+
+from dataclasses import asdict
+from typing import Any, Protocol
+
+from wf_artifacts import (
+    DependencyDiagnostic,
+    RunStore,
+    WorkflowArtifact,
+    WorkflowDeployment,
+)
+from wf_core import RunState
+
+from .deployments import WorkflowDeploymentApi, _available_sources
+from .models import RawWorkflowPlan
+from .next_actions import NextActions
+from .run_lifecycle import (
+    create_pinned_environment,
+    has_blocking_diagnostics,
+    load_stored_run,
+    mark_resume_blocked,
+    persist_stopped_run,
+    restore_interrupted_run,
+    validate_pinned_resume_environment,
+)
+from .saved_subgraphs import saved_subgraph_tree_from_snapshots
+from .operation_context import WorkflowOperationContext
+
+
+class TraceRangeLike(Protocol):
+    """Small structural trace range accepted from MCP, CLI, or HTTP adapters."""
+
+    start: int
+    limit: int
+
+
+class WorkflowRunApi:
+    """Deployment run lifecycle operations.
+
+    Runtime execution stays behind WorkflowOperationContext.runtime so wf_api
+    does not depend on MCP service internals.
+    """
+
+    def __init__(self, context: WorkflowOperationContext) -> None:
+        self.context = context
+        self.deployments = WorkflowDeploymentApi(context)
+
+    def _run_store(self) -> RunStore:
+        if self.context.run_store is None:
+            raise KeyError("workflow run store is not configured")
+        return self.context.run_store
+```
+
+Use `TraceRangeLike | None` for run methods. This lets handler methods pass
+their MCP Pydantic `TraceRange` without importing it into `wf_api`.
+
+- [ ] **Step 2: Export run service**
+
+In `src/wf_api/__init__.py`:
+
+```python
+from .runs import WorkflowRunApi
+```
+
+Add `"WorkflowRunApi"` to `__all__`.
+
+---
+
+## Task 3: Move Run Methods
+
+**Files:**
+
+- Modify: `src/wf_api/runs.py`
+
+- [ ] **Step 1: Move `run_deployment`**
+
+Move the current handler body into `WorkflowRunApi.run_deployment(...)`.
+
+Required replacements:
+
+```python
+self._deployments.deployment_validation(...) -> self.deployments.deployment_validation(...)
+self.service.run_workflow_from_plan(...) -> self.context.runtime.run_workflow_from_plan(...)
+self._run_store() -> self._run_store()
+```
+
+Call runtime with the same arguments:
+
+```python
+run = await self.context.runtime.run_workflow_from_plan(
+    plan,
+    workflow_input,
+    deployment=deployment,
+    artifact=artifact,
+    saved_subgraph_tree=tree,
+)
+```
+
+- [ ] **Step 2: Move `resume_run`**
+
+Move the current handler body into `WorkflowRunApi.resume_run(...)`.
+
+Required replacements:
+
+```python
+validate_pinned_resume_environment(..., sources=_available_sources(self.service))
+```
+
+becomes:
+
+```python
+validate_pinned_resume_environment(
+    record=record,
+    sources=_available_sources(self.context.capability_sources),
+)
+```
+
+Call runtime with:
+
+```python
+run = await self.context.runtime.resume_workflow_from_plan(
+    plan,
+    stopped_run,
+    resume_payload=resume_payload,
+    resume_outcome=resume_outcome,
+    deployment=environment.deployment,
+    artifact=environment.root_artifact,
+    saved_subgraph_tree=tree,
+)
+```
+
+- [ ] **Step 3: Move stopped-run readers**
+
+Move:
+
+```text
+inspect_run
+read_run_trace
+```
+
+Preserve current payload shape:
+
+- `inspect_run` returns no trace list.
+- `read_run_trace` returns only `trace_range.start : start + limit`.
+- both include `trace_count`.
+- both include `next_actions` via `_run_payload`.
+
+---
+
+## Task 4: Move Run Helpers
+
+**Files:**
+
+- Modify: `src/wf_api/runs.py`
+- Modify: `src/wf_mcp/workflow_surface/handlers.py`
+
+- [ ] **Step 1: Add private helpers to `wf_api.runs`**
+
+Move or duplicate these helpers into `src/wf_api/runs.py`:
+
+```text
+_raw_plan_from_artifact
+_plan_field
+_run_payload
+_interrupt_payload
+```
+
+Keep the trace comment inside `_run_payload`:
+
+```python
+# Trace entries can grow quickly, so the public run tool only includes
+# a bounded debug slice when the caller explicitly asks for a range.
+```
+
+This comment is important because trace bloat is a public UX boundary.
+
+- [ ] **Step 2: Keep handler copies only if needed**
+
+After handler delegation, run:
+
+```powershell
+rg -n "_raw_plan_from_artifact|_run_payload|_interrupt_payload|_plan_field" src/wf_mcp/workflow_surface/handlers.py
+```
+
+Expected:
+
+- `_raw_plan_from_artifact` likely remains because `_call_wrapper_artifact` still uses it.
+- `_plan_field` remains if `_raw_plan_from_artifact` remains.
+- `_run_payload` and `_interrupt_payload` should be removable if no handler run methods remain.
+
+Remove only helpers with no remaining handler callers.
+
+---
+
+## Task 5: Wire `WorkflowSurfaceHandlers`
+
+**Files:**
+
+- Modify: `src/wf_mcp/workflow_surface/handlers.py`
+
+- [ ] **Step 1: Add import**
+
+```python
+from wf_api.runs import WorkflowRunApi
+```
+
+- [ ] **Step 2: Instantiate run service**
+
+In `WorkflowSurfaceHandlers.__init__`, reuse the same context object:
+
+```python
+context = context_from_service(service)
+self._drafts = WorkflowDraftApi(context)
+self._artifacts = WorkflowArtifactApi(context)
+self._deployments = WorkflowDeploymentApi(context)
+self._runs = WorkflowRunApi(context)
+```
+
+Do not call `context_from_service(service)` separately for every domain service.
+
+- [ ] **Step 3: Replace run method bodies with delegates**
+
+Replace:
+
+```text
+run_deployment
+resume_run
+inspect_run
+read_run_trace
+```
+
+Example:
+
+```python
+async def inspect_run(self, *, run_id: str) -> dict[str, Any]:
+    """Return one durable stopped-run summary without debug trace entries."""
+    return await self._runs.inspect_run(run_id=run_id)
+```
+
+For `trace_range`, pass the MCP model object through directly:
+
+```python
+return await self._runs.run_deployment(
+    deployment_id=deployment_id,
+    workflow_input=workflow_input,
+    trace_range=trace_range,
+)
+```
+
+`WorkflowRunApi` accepts it structurally through `TraceRangeLike`.
+
+- [ ] **Step 4: Remove now-unused imports**
+
+After replacing run methods, remove imports from `handlers.py` only if `ruff`
+confirms they are unused. Likely candidates:
+
+```text
+dataclasses.asdict
+RunStore
+run_lifecycle helpers
+saved_subgraph_tree_from_snapshots
+```
+
+Do not remove `SavedSubgraphTree`, `direct_wrapper_interrupt_diagnostic`,
+`resolve_saved_subgraph_tree`, or `_raw_plan_from_artifact` if wrapper/capability
+methods still need them.
+
+---
+
+## Task 6: Add Focused Run API Tests
+
+**Files:**
+
+- Create: `tests/wf_api/test_run_api.py`
+
+- [ ] **Step 1: Cover unrunnable deployment path**
+
+Create a test that saves a deployment with missing/unbound requirements and
+asserts:
+
+```python
+result = asyncio.run(api.run_deployment(...))
+assert result["status"] == "unrunnable"
+assert result["run_id"] is None
+assert result["trace_count"] == 0
+assert result["diagnostics"][0]["code"]
+```
+
+- [ ] **Step 2: Cover completed run persistence**
+
+Use existing test helpers (`echo_tool`, local temp store patterns) to register a
+valid source, save an artifact/deployment, run it, and assert:
+
+```python
+assert result["status"] == "completed"
+assert isinstance(result["run_id"], str)
+assert result["resume_readiness"] == "not_applicable"
+assert result["trace_count"] >= 1
+```
+
+Then load the run from the run store and assert it exists.
+
+- [ ] **Step 3: Cover inspect and bounded trace**
+
+After a completed run:
+
+```python
+summary = asyncio.run(api.inspect_run(run_id=run_id))
+trace = asyncio.run(api.read_run_trace(run_id=run_id, trace_range=SimpleTraceRange(start=0, limit=1)))
+```
+
+Assert:
+
+```python
+assert "trace" not in summary
+assert trace["trace_start"] == 0
+assert trace["trace_limit"] == 1
+assert len(trace["trace"]) <= 1
+assert trace["trace_count"] == summary["trace_count"]
+```
+
+Define local helper:
+
+```python
+@dataclass(frozen=True)
+class SimpleTraceRange:
+    start: int
+    limit: int
+```
+
+- [ ] **Step 4: Cover handler delegation**
+
+Add one smoke test comparing stable fields from:
+
+```python
+handler_result = asyncio.run(WorkflowSurfaceHandlers(service).inspect_run(run_id=run_id))
+api_result = asyncio.run(WorkflowRunApi(context_from_service(service)).inspect_run(run_id=run_id))
+```
+
+Compare `status`, `run_id`, `trace_count`, and `resume_readiness` individually.
+
+Do not duplicate every old workflow-surface run test. `wf_api` should own run
+behavior; `wf_mcp` should keep only adapter/schema/delegation coverage.
+
+---
+
+## Task 7: Verification
+
+- [ ] **Step 1: Run focused run tests**
+
+```powershell
+uv run pytest tests/wf_api/test_run_api.py tests/wf_mcp/workflow_surface/test_runs.py -q
+```
+
+Expected: pass.
+
+- [ ] **Step 2: Run deployment/artifact tests because runs reuse them**
+
+```powershell
+uv run pytest tests/wf_api/test_artifact_api.py tests/wf_api/test_deployment_api.py tests/wf_api/test_operation_context.py -q
+```
+
+Expected: pass.
+
+- [ ] **Step 3: Run import-direction test**
+
+```powershell
+uv run pytest tests/wf_api/test_import_direction.py -q
+```
+
+Expected: pass; `wf_api` has no `wf_mcp` imports.
+
+- [ ] **Step 4: Run ruff on touched files**
+
+```powershell
+uv run ruff check src/wf_api/runs.py src/wf_api/operation_context.py src/wf_api/__init__.py src/wf_mcp/broker/service/workflow_operation_context.py src/wf_mcp/workflow_surface/handlers.py tests/wf_api/test_run_api.py
+```
+
+Expected: all checks pass.
+
+- [ ] **Step 5: Run basedpyright on touched files**
+
+```powershell
+uv run basedpyright --level error src/wf_api/runs.py src/wf_api/operation_context.py src/wf_mcp/broker/service/workflow_operation_context.py src/wf_mcp/workflow_surface/handlers.py tests/wf_api/test_run_api.py
+```
+
+Expected: `0 errors`.
+
+- [ ] **Step 6: Optional full suite**
+
+```powershell
+uv run pytest -q
+```
+
+Expected: full suite passes with the project’s existing skipped/xfailed counts.
+
+---
+
+## Self-Review Checklist
+
+- `wf_api.runs` imports no `wf_mcp`.
+- Runtime execution goes through `WorkflowOperationContext.runtime`.
+- Run persistence uses `WorkflowOperationContext.run_store`.
+- `WorkflowSurfaceHandlers` public run signatures are unchanged.
+- `TraceRange` stays structural at the `wf_api` layer.
+- Trace list remains opt-in and bounded.
+- `resume_run` still blocks when pinned dependency validation fails.
+- Capability direct wrapper calls still work because handler keeps `_raw_plan_from_artifact` if needed.
+- No public payload shape changed.
+- No MCP schema changed.