Skip to content

wspkit

wspkit is a Python library and command-line client for the Workflow Server Protocol (WSP) — a small JSON-RPC 2.0 protocol that lets workflow tools (environment managers, task runners, test runners) expose their capabilities to consuming tools through a uniform interface.

WSP is to workflow tools roughly what the Language Server Protocol is to editors: a stable, machine-readable surface that decouples the tool from the client.

Why use wspkit

  • Two integration paths. Take a runtime dependency on the library and register Python callables, or stay completely decoupled by writing a TOML or JSON config file that points at imports or external commands.
  • A complete CLI client. The bundled wsp command performs the per-invocation lifecycle (initialize → method → shutdown → exit), translates JSON-RPC error responses into well-defined exit codes, and prints results as JSON.
  • A useful out-of-the-box experience. When no target is configured, wsp serves a built-in workflow tool backed by Python's standard venv module with on-disk persistence, so you get working environment/* calls before installing anything else.
  • Conformance you can rely on. The protocol implementation is verified against property-based tests covering the JSON-RPC codec, the Content-Length framing, the lifecycle finite-state machine, and the error model. See Testing for the property catalogue.

Where to start

Project status

wspkit is a young library. The first iteration ships:

  • The WSP_Server runtime over stdio with Content-Length framing.
  • Programmatic and Config_File handler registration.
  • The lifecycle methods (initialize, shutdown, exit) and the environment/* family (list, create, get, delete, execute).
  • The wsp CLI client and the bundled fallback workflow tool.

Future iterations will add Python interpreter installation endpoints, test endpoints, and task endpoints. See the WSP method reference for the current surface.