115 lines
4.5 KiB
Markdown
115 lines
4.5 KiB
Markdown
# CLI / API Alignment Notes
|
|
|
|
## Context
|
|
|
|
`wf_api.WorkflowApiSurface` is now the shared workflow operation contract.
|
|
`WorkflowApi` implements it in-process, and `RpcWorkflowApiClient` implements it
|
|
by calling fixed JSON-RPC methods. The CLI now uses target-aware context for the
|
|
basic workflow lifecycle:
|
|
|
|
- capability list/inspect
|
|
- draft workspace list/inspect/create/patch/validate/save
|
|
- artifact list/inspect
|
|
- deployment list/inspect/save/validate/delete
|
|
- run start/inspect/trace/resume
|
|
|
|
This means `wf` can target either:
|
|
|
|
- `local`: same-process stores/runtime built from config
|
|
- `rpc_http`: a long-lived workflow server that owns its own stores/runtime
|
|
|
|
The target store is the authority. For example, `wf run resume` does not resume
|
|
"client-local" state when pointed at `--url`; it resumes the run persisted in the
|
|
server's run store.
|
|
|
|
## Current Boundary
|
|
|
|
```text
|
|
CLI command
|
|
-> CliContext.handlers: WorkflowApiSurface
|
|
-> WorkflowApi # local target
|
|
-> RpcWorkflowApiClient # rpc_http target
|
|
```
|
|
|
|
Server side:
|
|
|
|
```text
|
|
JSON-RPC request
|
|
-> wf_transport_rpc_http methods_* module
|
|
-> WorkflowServer.api: WorkflowApi
|
|
-> wf_api domain service
|
|
-> WorkflowOperationContext
|
|
```
|
|
|
|
The JSON-RPC transport is split by workflow domain. `RpcWorkflowApiClient`
|
|
remains one flat surface implementation, backed by a base transport plus
|
|
stateless domain mixins.
|
|
|
|
## Design Rules
|
|
|
|
- CLI commands should type against `WorkflowApiSurface` whenever they can work
|
|
with local or remote targets.
|
|
- Use `load_local_cli_context_from_typer` only for commands that truly need
|
|
same-process access to stores, config files, or non-surface internals.
|
|
- Remote clients should not infer workflow state from client-local config. The
|
|
selected target owns persisted runs, deployments, artifacts, and draft
|
|
workspaces.
|
|
- JSON-RPC methods remain fixed and dotted, such as `workflow.runs.resume`.
|
|
Do not dynamically register saved workflows as JSON-RPC methods.
|
|
- Transport packages adapt calls. Workflow validation, resume policy, wrapper
|
|
hints, and next actions stay in `wf_api`.
|
|
|
|
## Local-Only Audit Result
|
|
|
|
Audit result: no workflow lifecycle command imports
|
|
`load_local_cli_context_from_typer`. The capability, draft workspace, artifact,
|
|
deployment, and run command groups all load `CliContext.handlers:
|
|
WorkflowApiSurface`, so they can target either local or JSON-RPC HTTP.
|
|
|
|
The remaining non-lifecycle command groups are static/local by design for now:
|
|
|
|
- `wf docs`
|
|
- `wf schema`
|
|
- `wf explain`
|
|
|
|
`wf docs` and `wf schema` are currently empty Typer groups reserved for future
|
|
commands. `wf explain` reads the packaged explanation registry and does not need
|
|
workflow stores or remote server state. If these need remote behavior later,
|
|
decide whether they belong on `WorkflowApiSurface`, a sibling admin/docs
|
|
surface, or plain local CLI utilities.
|
|
|
|
## Next Slices
|
|
|
|
1. **Store-backed source registry**
|
|
- Read-only source/admin operations are now available through JSON-RPC HTTP
|
|
and `wf source list` / `wf source inspect`.
|
|
- Read-only admin/config operations are now available through JSON-RPC HTTP
|
|
and `wf admin connections`, `wf admin statuses`, and `wf admin events`.
|
|
- Source registry mutations (`add` / `update` / `enable` / `disable` /
|
|
`remove`) are now implemented for server-owned dynamic source changes.
|
|
- Remaining source-registry work is migration policy: config can bootstrap
|
|
or lock sources, while the store-backed registry owns mutable desired
|
|
state for dynamic sources.
|
|
|
|
2. **Mutable source/admin commands**
|
|
- Config can bootstrap sources, but server-owned dynamic source changes
|
|
should persist through the store.
|
|
- Keep source identity structural: source id, provider/account/profile, and
|
|
concrete transport details should not be inferred from dotted display names.
|
|
|
|
3. **Transport sibling planning**
|
|
- JSON-RPC over HTTP is the first transport.
|
|
- If streaming/progress becomes important, add a WebSocket transport sibling
|
|
rather than changing workflow semantics.
|
|
- A future MCP server transport can expose the same server-owned
|
|
`WorkflowApiSurface` plus any sibling admin/docs surfaces.
|
|
|
|
## Open Questions
|
|
|
|
- Source/admin and admin/config read-only operations currently live in `wf_api`
|
|
as sibling surfaces. If mutation grows into a larger management domain, split
|
|
that later instead of overloading `WorkflowApiSurface`.
|
|
- Should `wf schema` describe local CLI command payloads only, or query a remote
|
|
server for supported method schemas?
|
|
- Should `wf docs` read packaged local docs, remote server docs, or both?
|