Wity Universal Command Envelope (WUCE) Spec v2.3

Extending Wity’s Dialectic Chain currently used for dialogue templating in wity agents, for other environments - like running filesystem commands, or running a cad software application etc. as a progressive dialogue.

1. Purpose

Wity's Universal Command Envelope (WUCE) is a deterministic, environment-agnostic, structured JSON format to represent sequences of commands or operations as dialgoue.

Design Principle:

Represent any domain/environment: filesystem, CAD, database, APIs, shell, cloud, LLMs, etc.
Encode sequential and parallel operations with explicit dependencies.
Enable deterministic execution (not deterministic outcome) by agents, LLMs, or orchestration engines. Keep only what is necessary for deterministic execution.
Be transport-agnostic: can be embedded in JSON-RPC, HTTP payloads, WebSockets, or any messaging system.
Avoid encoding logging, streaming, preconditions, retry, output management policies inside the envelope
1. Let executors/agents decide error handling, output streaming, retries & other such things as embedding these reduces portability and generality.

2. Envelope Structure

[

{

"stepName": "string",

"stepDescription": "string",

"stepMsg": "string",

"actionDomain": "string",

"observationDomain": "string",

"observe": "string",

"actionType": "string",

"actionMeta": {},

"yield": ["string", "string"]

},
…
…

]

3. Field Definitions

Field	Type	Description
stepName	string	Unique, human-readable name of the step/task (noun form).
stepDescription	string	Static description of what the step does (timeless / third-person).
stepMsg	string	Verb-inflected runtime message representing the step in execution (e.g., “Renaming file1.txt”).
actionDomain	string (optional)	Logical environment or capability domain (e.g., filesystem, cad, database).
observationDomain	string (optional)	Domain from which events are observed for dependencies.
observe	string	Event or condition this step depends on before executing. Empty if none.
actionType	string	Type of operation or activity this step performs (e.g., cd, add_cube, query).
actionMeta	object	Parameters or context for the action. JSON Schema validation recommended.
yield	array of strings	Events or outputs emitted by this step, which may trigger other steps.

4. Extensibility

The WUCE structure is designed to evolve without breaking compatibility:

Action Domains: New domains (e.g., filesystem, cad, ml_model, iot) can be added without changing the envelope structure.
Action Types: New actions can be introduced within any domain.
Action Meta: Parameters for actions (actionMeta) can be extended or typed per actionDomain + actionType.
Steps / Observables: New observe events or yield outputs can be added to define dependencies or trigger other steps dynamically.
Step Fields: Fields like stepMsg can be enhanced or extended (e.g., richer runtime info) without affecting backward compatibility.
Execution policies (timeouts, retries, priorities, conditional logic) are intentionally external to the WUCE. They are applied by the consumer programs, agents, or workflow engines interpreting the sequence.

5. Examples

5.1 Filesystem Example

[

{

"stepName": "Change Directory",

"stepDescription": "Move to the docs folder",

"stepMsg": "Moving to docs folder",

"actionDomain": "filesystem",

"observationDomain": "",

"observe": "",

"actionType": "cd",

"actionMeta": { "path": "/home/user/docs" },

"yield": ["cwd:changed"]

{

"stepName": "Rename File",

"stepDescription": "Rename file1.txt to file2.txt",

"stepMsg": "Renaming file1.txt to file2.txt",

"actionDomain": "filesystem",

"observationDomain": "filesystem",

"observe": "cwd:changed",

"actionType": "mv",

"actionMeta": { "from": "file1.txt", "to": "file2.txt" },

"yield": ["file:renamed"]

{

"stepName": "Delete Temporary File",

"stepDescription": "Remove tmp.txt",

"stepMsg": "Deleting tmp.txt",

"actionDomain": "filesystem",

"observationDomain": "filesystem",

"observe": "cwd:changed",

"actionType": "rm",

"actionMeta": { "path": "/home/user/docs/tmp.txt" },

"yield": ["file:deleted"]

}

]

5.2 CAD Example with Parallel Steps

[

{

"stepName": "Get Confirmation",

"stepDescription": "Allow me to create cad part",

"stepMsg": "Creating CAD part assembly_1",

"actionDomain": "user",

"observationDomain": "user",

"observe": "user_confirmation_for_part_creation",

"actionType": "confirmation_prompt",

"actionMeta": { "query": "Can I proceed creating new CAD parts?" },

"yield": ["user_confirmation_for_part_creation"]

{

"stepName": "Create Part",

"stepDescription": "Initialize a new CAD part called assembly_1",

"stepMsg": "Creating CAD part assembly_1",

"actionDomain": "cad",

"observationDomain": "user",

"observe": "user_confirmation_for_part_creation",

"actionType": "create_part",

"actionMeta": { "part_name": "assembly_1" },

"yield": ["part:created"]

{

"stepName": "Add Cube",

"stepDescription": "Add a cube of size 10x20x10",

"stepMsg": "Adding cube 10x20x10",

"actionDomain": "cad",

"observationDomain": "cad",

"observe": "part:created",

"actionType": "add_cube",

"actionMeta": { "width": 10, "height": 20, "depth": 10 },

"yield": ["cube:added"]

{

"stepName": "Add Cylinder",

"stepDescription": "Add a cylinder with radius 5, height 30, positioned at [5,0,0]",

"stepMsg": "Adding cylinder radius 5, height 30 at position [5,0,0]",

"actionDomain": "cad",

"observationDomain": "cad",

"observe": "part:created",

"actionType": "add_cylinder",

"actionMeta": { "radius": 5, "height": 30, "position": [5, 0, 0] },

"yield": ["cylinder:added"]

{

"stepName": "Boolean Union",

"stepDescription": "Combine cube and cylinder into one object",

"stepMsg": "Unioning cube and cylinder",

"actionDomain": "cad",

"observationDomain": "cad",

"observe": "cube:added",

"actionType": "boolean_union",

"actionMeta": { "objects": ["cube:added", "cylinder:added"] },

"yield": ["union:done"]

{

"stepName": "Export Part",

"stepDescription": "Export the assembly as STL file",

"stepMsg": "Exporting assembly_1.stl",

"actionDomain": "cad",

"observationDomain": "cad",

"observe": "union:done",

"actionType": "export_part",

"actionMeta": { "format": "STL", "filename": "assembly_1.stl" },

"yield": ["file:exported"]

}

]

6. Transport Layer

WUCE is transport-agnostic:

Can be embedded in JSON-RPC:

{

"jsonrpc": "2.0",

"id": "uuid-xyz",

"method": "execute_commands",

"params": { ...WUCE... }

}

Or sent over HTTP, WebSocket, Kafka, or other messaging systems.
The envelope itself is self-contained for deterministic execution.