120 lines
4.6 KiB
Markdown
120 lines
4.6 KiB
Markdown
# Workflow Artifact Hardening 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:** Make saved workflow artifacts safe enough to rely on before merging MCP server modes or exposing workflow execution more broadly.
|
|
|
|
**Architecture:** Keep `wf_artifacts` provider-neutral. `wf_mcp` may project artifact operations, but validation, storage, artifact creation, and diagnostics should stay in `wf_artifacts` where possible.
|
|
|
|
**Tech Stack:** Python 3.14, Pydantic v2, pytest, `wf_core.Workflow` validation, existing `wf_mcp` broker service.
|
|
|
|
---
|
|
|
|
## Why This Comes First
|
|
|
|
The live Codex probe proved the artifact execution path works, but it also found
|
|
a real weakness: `create_workflow_artifact_from_plan` saved an invalid
|
|
`state_schema` shape, and the error surfaced only when `run_workflow_deployment`
|
|
tried to compile the workflow.
|
|
|
|
Before unifying broker and transparent proxy modes, artifact creation should
|
|
reject invalid plans earlier and return structured diagnostics.
|
|
|
|
## Scope
|
|
|
|
This plan hardens saved workflow creation and dependency validation. It does not
|
|
merge MCP server modes and does not add native subgraphs.
|
|
|
|
## Tasks
|
|
|
|
### Task 1: Validate Plan Shape During Artifact Creation
|
|
|
|
**Files:**
|
|
|
|
- Modify: `src/wf_artifacts/factory.py`
|
|
- Test: `tests/artifacts/test_factory.py`
|
|
|
|
- [ ] Add a failing test proving `create_workflow_artifact_from_plan` rejects a
|
|
plan that cannot become a `wf_core.Workflow`.
|
|
- [ ] Implement validation by constructing `wf_core.Workflow.model_validate`
|
|
from the plan fields.
|
|
- [ ] Keep the validation dependency one-way: `wf_artifacts` may import
|
|
`wf_core`, but `wf_core` must not import `wf_artifacts`.
|
|
- [ ] Return `ValueError` with a concise message containing the failing field
|
|
path or Pydantic error message.
|
|
- [ ] Run `uv run --with pytest pytest tests\artifacts\test_factory.py -q`.
|
|
|
|
### Task 2: Add Artifact Creation Diagnostics
|
|
|
|
**Files:**
|
|
|
|
- Modify: `src/wf_artifacts/models.py`
|
|
- Modify: `src/wf_artifacts/factory.py`
|
|
- Test: `tests/artifacts/test_factory.py`
|
|
|
|
- [ ] Decide whether creation failures should raise exceptions only or also
|
|
expose a `validate_workflow_artifact_plan(...) -> list[DependencyDiagnostic]`
|
|
style function.
|
|
- [ ] Recommended v1: add a separate `validate_workflow_artifact_plan(plan)`
|
|
that returns structured diagnostics, while the factory still raises on errors.
|
|
- [ ] Add tests for missing `input_schema`, missing `output_schema`, invalid
|
|
state schema, and missing start node.
|
|
|
|
### Task 3: Validate Direct Workflow Dependencies
|
|
|
|
**Files:**
|
|
|
|
- Modify: `src/wf_artifacts/validation.py`
|
|
- Test: `tests/artifacts/test_validation.py`
|
|
|
|
- [ ] Add artifact-store-aware validation for `workflow_dependencies`.
|
|
- [ ] Validate exact artifact-version pins.
|
|
- [ ] Return `dependency_missing` when a child artifact version does not exist.
|
|
- [ ] Return `dependency_cycle` when direct/transitive workflow artifact
|
|
dependencies cycle.
|
|
- [ ] Do not copy child dependency snapshots into the parent.
|
|
|
|
### Task 4: Improve Capability Contract Checking
|
|
|
|
**Files:**
|
|
|
|
- Modify: `src/wf_artifacts/validation.py`
|
|
- Test: `tests/artifacts/test_validation.py`
|
|
- Optional: `src/wf_mcp/broker/artifact_tools.py`
|
|
|
|
- [ ] Preserve current hash comparison behavior.
|
|
- [ ] Add tests for kind mismatch, for example required `tool` but available
|
|
`node_spec`.
|
|
- [ ] Decide whether `node_spec` can satisfy `tool` when the provider is an MCP
|
|
wrapper. Recommended: no implicit kind coercion in `wf_artifacts`; adapters
|
|
should present the available kind they mean to expose.
|
|
- [ ] Add diagnostics with `code="capability_kind_mismatch"`.
|
|
|
|
### Task 5: Document Current Runtime Limitations In Tool Responses
|
|
|
|
**Files:**
|
|
|
|
- Modify: `src/wf_mcp/broker/artifact_tools.py`
|
|
- Test: `tests/wf_mcp/test_broker_server.py`
|
|
|
|
- [ ] Keep interrupting artifacts rejected by `run_workflow_deployment`.
|
|
- [ ] Add `repair_hint` text explaining native subgraphs/nested resume are not
|
|
implemented yet.
|
|
- [ ] Add a test proving unsupported interrupt artifacts return a diagnostic
|
|
instead of raising.
|
|
|
|
## Verification
|
|
|
|
- [ ] `uv run --with pytest pytest tests\artifacts -q`
|
|
- [ ] `uv run --with pytest pytest tests\wf_mcp\test_broker_server.py -q`
|
|
- [ ] `uv run --with pytest pytest -q`
|
|
- [ ] `uv run ruff check src tests examples main.py`
|
|
- [ ] `uv run basedpyright src tests examples main.py --level error`
|
|
|
|
## Non-Goals
|
|
|
|
- No native `wf_core` subgraph implementation.
|
|
- No MCP Tasks implementation.
|
|
- No run history persistence.
|
|
- No broker/transparent mode merge in this plan.
|