Protocol navigation

Protocol Reference

HotRepl v2 — one WebSocket connection, JSON frames, all operations.

Connection

Messages exchanged when a WebSocket connection opens or the session changes.

handshake S→C v2

Sent immediately after the WebSocket opens. Advertises host identity, evaluator capabilities, runtime limits, and typed-command support.

Example

{
  "type": "handshake",
  "protocolVersion": 2,
  "host": { "name": "BepInEx", "version": "0.x", "platform": "Unity Mono" },
  "evaluator": {
    "name": "Mono.CSharp",
    "languageVersion": "7.x",
    "persistentState": true,
    "supportsCompletion": true,
    "cancellation": "hardAbort"
  },
  "availableEvaluators": ["Mono.CSharp"],
  "defaultUsings": ["System"],
  "helpers": ["String[] Help()"],
  "control": { "supported": true, "commandsListChanged": false, "schemaValidation": false },
  "limits": {
    "maxMessageBytes": 4194304,
    "maxQueuedCommands": 32,
    "maxResultLength": 102400,
    "maxEnumerableElements": 100,
    "defaultEvalTimeoutMs": 10000,
    "maxJobConcurrency": 1
  },
  "enforces": ["maxMessageBytes", "maxQueuedCommands", "maxResultLength",
               "maxEnumerableElements", "maxJobConcurrency"]
}

JSON Schema

{
  "type": "object",
  "required": [
    "type",
    "protocolVersion",
    "host",
    "evaluator",
    "availableEvaluators",
    "defaultUsings",
    "helpers",
    "control",
    "limits",
    "enforces"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "handshake"
    },
    "protocolVersion": {
      "type": "number",
      "const": 2
    },
    "host": {
      "type": "object",
      "required": [
        "name",
        "version",
        "platform"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "version": {
          "type": "string"
        },
        "platform": {
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "evaluator": {
      "type": "object",
      "required": [
        "name",
        "languageVersion",
        "persistentState",
        "supportsCompletion",
        "cancellation"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "languageVersion": {
          "type": "string"
        },
        "persistentState": {
          "type": "boolean"
        },
        "supportsCompletion": {
          "type": "boolean"
        },
        "cancellation": {
          "anyOf": [
            {
              "type": "string",
              "const": "cooperative"
            },
            {
              "type": "string",
              "const": "hardAbort"
            },
            {
              "type": "string",
              "const": "unsupported"
            }
          ]
        }
      },
      "additionalProperties": false
    },
    "availableEvaluators": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "defaultUsings": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "helpers": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "control": {
      "type": "object",
      "required": [
        "supported",
        "commandsListChanged",
        "schemaValidation"
      ],
      "properties": {
        "supported": {
          "type": "boolean"
        },
        "commandsListChanged": {
          "type": "boolean"
        },
        "schemaValidation": {
          "type": "boolean"
        }
      },
      "additionalProperties": false
    },
    "limits": {
      "type": "object",
      "required": [
        "maxMessageBytes",
        "maxQueuedCommands",
        "maxResultLength",
        "maxEnumerableElements",
        "defaultEvalTimeoutMs",
        "maxJobConcurrency"
      ],
      "properties": {
        "maxMessageBytes": {
          "type": "integer",
          "minimum": 1
        },
        "maxQueuedCommands": {
          "type": "integer",
          "minimum": 0
        },
        "maxResultLength": {
          "type": "integer",
          "minimum": 1
        },
        "maxEnumerableElements": {
          "type": "integer",
          "minimum": 1
        },
        "defaultEvalTimeoutMs": {
          "type": "integer",
          "minimum": 1
        },
        "maxJobConcurrency": {
          "type": "integer",
          "minimum": 1
        }
      },
      "additionalProperties": false
    },
    "enforces": {
      "type": "array",
      "items": {
        "anyOf": [
          {
            "type": "string",
            "const": "maxMessageBytes"
          },
          {
            "type": "string",
            "const": "maxQueuedCommands"
          },
          {
            "type": "string",
            "const": "maxResultLength"
          },
          {
            "type": "string",
            "const": "maxEnumerableElements"
          },
          {
            "type": "string",
            "const": "maxJobConcurrency"
          }
        ]
      }
    }
  },
  "additionalProperties": false
}

session_evicted S→C v2

Sent to the previous client when a new WebSocket connection replaces it. Active subscriptions are closed.

Example

{ "type": "session_evicted", "reason": "new_connection" }

JSON Schema

{
  "type": "object",
  "required": [
    "type",
    "reason"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "session_evicted"
    },
    "reason": {
      "type": "string"
    },
    "by": {
      "type": "object",
      "properties": {
        "clientName": {
          "type": "string"
        }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}

assembly_reload S→C v2

Sent when the game hot-reloads an assembly. Currently not routed by the SDK transport; clients observe this as an unsolicited push.

Example

{ "type": "assembly_reload", "assembly": "HotRepl.Plugin.dll", "message": "Assembly reload complete." }

JSON Schema

{
  "type": "object",
  "required": [
    "type",
    "message"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "assembly_reload"
    },
    "assembly": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

error S→C v2

Protocol-level error not attributable to a specific request. Has an optional id when a request triggered it.

Example

{
  "type": "error",
  "error": {
    "kind": "invalid_request",
    "code": "malformedJson",
    "message": "Could not parse the incoming JSON frame.",
    "retryable": false
  }
}

JSON Schema

{
  "type": "object",
  "required": [
    "type",
    "error"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "error"
    },
    "id": {
      "type": "string"
    },
    "error": {
      "type": "object",
      "required": [
        "kind",
        "code",
        "message",
        "retryable"
      ],
      "properties": {
        "kind": {
          "anyOf": [
            {
              "type": "string",
              "const": "validation_failed"
            },
            {
              "type": "string",
              "const": "precondition_failed"
            },
            {
              "type": "string",
              "const": "conflict"
            },
            {
              "type": "string",
              "const": "timeout"
            },
            {
              "type": "string",
              "const": "cancelled"
            },
            {
              "type": "string",
              "const": "busy"
            },
            {
              "type": "string",
              "const": "unknown_command"
            },
            {
              "type": "string",
              "const": "unsupported_operation"
            },
            {
              "type": "string",
              "const": "artifact_missing"
            },
            {
              "type": "string",
              "const": "invalid_request"
            },
            {
              "type": "string",
              "const": "internal"
            }
          ]
        },
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "retryable": {
          "type": "boolean"
        },
        "details": {}
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}

Eval

C# expression evaluation on the game's main thread.

eval C→S v2

Submit a C# expression for evaluation. The evaluator state persists between evals until reset.

Example

{ "type": "eval", "id": "eval-1", "code": "1 + 1", "timeoutMs": 10000 }

JSON Schema

{
  "type": "object",
  "required": [
    "type",
    "id",
    "code"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "eval"
    },
    "id": {
      "type": "string"
    },
    "code": {
      "type": "string"
    },
    "timeoutMs": {
      "type": "number"
    }
  },
  "additionalProperties": false
}

eval_result S→C v2

Returned when the expression completes without a runtime exception. Matched to the request by id.

Example

{
  "type": "eval_result",
  "id": "eval-1",
  "hasValue": true,
  "value": "2",
  "valueType": "System.Int32",
  "durationMs": 3
}

JSON Schema

{
  "type": "object",
  "required": [
    "type",
    "id",
    "hasValue",
    "durationMs"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "eval_result"
    },
    "id": {
      "type": "string"
    },
    "hasValue": {
      "type": "boolean"
    },
    "value": {},
    "valueType": {
      "type": "string"
    },
    "stdout": {
      "type": "string"
    },
    "durationMs": {
      "type": "number"
    }
  },
  "additionalProperties": false
}

eval_error S→C v2

Returned when the expression throws or the evaluator reports a compile error.

Example

{
  "type": "eval_error",
  "id": "eval-1",
  "error": {
    "kind": "internal",
    "code": "runtimeException",
    "message": "NullReferenceException: Object reference not set to an instance of an object.",
    "retryable": false
  }
}

JSON Schema

{
  "type": "object",
  "required": [
    "type",
    "id",
    "error"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "eval_error"
    },
    "id": {
      "type": "string"
    },
    "error": {
      "type": "object",
      "required": [
        "kind",
        "code",
        "message",
        "retryable"
      ],
      "properties": {
        "kind": {
          "anyOf": [
            {
              "type": "string",
              "const": "validation_failed"
            },
            {
              "type": "string",
              "const": "precondition_failed"
            },
            {
              "type": "string",
              "const": "conflict"
            },
            {
              "type": "string",
              "const": "timeout"
            },
            {
              "type": "string",
              "const": "cancelled"
            },
            {
              "type": "string",
              "const": "busy"
            },
            {
              "type": "string",
              "const": "unknown_command"
            },
            {
              "type": "string",
              "const": "unsupported_operation"
            },
            {
              "type": "string",
              "const": "artifact_missing"
            },
            {
              "type": "string",
              "const": "invalid_request"
            },
            {
              "type": "string",
              "const": "internal"
            }
          ]
        },
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "retryable": {
          "type": "boolean"
        },
        "details": {}
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}

complete C→S v2

Request code-completion candidates for a partial expression.

Example

{ "type": "complete", "id": "c-1", "code": "UnityEngine.Application.pro" }

JSON Schema

{
  "type": "object",
  "required": [
    "type",
    "id",
    "code"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "complete"
    },
    "id": {
      "type": "string"
    },
    "code": {
      "type": "string"
    },
    "cursor": {
      "type": "number"
    }
  },
  "additionalProperties": false
}

complete_result S→C v2

Completion candidates for the submitted partial expression.

Example

{
  "type": "complete_result",
  "id": "c-1",
  "completions": ["productName", "productVersion", "platform"],
  "durationMs": 5
}

JSON Schema

{
  "type": "object",
  "required": [
    "type",
    "id",
    "completions",
    "durationMs"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "complete_result"
    },
    "id": {
      "type": "string"
    },
    "completions": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "durationMs": {
      "type": "number"
    }
  },
  "additionalProperties": false
}

reset C→S v2

Clear all persistent evaluator variables and type definitions.

Example

{ "type": "reset", "id": "r-1" }

JSON Schema

{
  "type": "object",
  "required": [
    "type",
    "id"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "reset"
    },
    "id": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

reset_result S→C v2

Confirmation that the evaluator state has been cleared.

Example

{ "type": "reset_result", "id": "r-1", "success": true }

JSON Schema

{
  "type": "object",
  "required": [
    "type",
    "id",
    "success"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "reset_result"
    },
    "id": {
      "type": "string"
    },
    "success": {
      "type": "boolean"
    }
  },
  "additionalProperties": false
}

Subscriptions

Repeating evals that run on a per-frame interval.

subscribe C→S v2

Start a frame subscription. The server evaluates code every intervalFrames frames and streams results until limit is reached or the subscription is cancelled.

Example

{
  "type": "subscribe",
  "id": "watch-1",
  "code": "Time.frameCount",
  "intervalFrames": 1,
  "limit": 10
}

JSON Schema

{
  "type": "object",
  "required": [
    "type",
    "id",
    "code"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "subscribe"
    },
    "id": {
      "type": "string"
    },
    "code": {
      "type": "string"
    },
    "intervalFrames": {
      "type": "number"
    },
    "limit": {
      "type": "number"
    }
  },
  "additionalProperties": false
}

subscribe_result S→C v2

One tick of a running subscription. final: true on the last tick.

Example

{
  "type": "subscribe_result",
  "id": "watch-1",
  "seq": 0,
  "hasValue": true,
  "value": "42",
  "valueType": "System.Int32",
  "durationMs": 3,
  "final": false
}

JSON Schema

{
  "type": "object",
  "required": [
    "type",
    "id",
    "seq",
    "hasValue",
    "durationMs",
    "final"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "subscribe_result"
    },
    "id": {
      "type": "string"
    },
    "seq": {
      "type": "number"
    },
    "hasValue": {
      "type": "boolean"
    },
    "value": {},
    "valueType": {
      "type": "string"
    },
    "durationMs": {
      "type": "number"
    },
    "final": {
      "type": "boolean"
    }
  },
  "additionalProperties": false
}

subscribe_error S→C v2

Subscription tick that produced an error. final: true terminates the subscription.

Example

{
  "type": "subscribe_error",
  "id": "watch-1",
  "seq": 0,
  "error": {
    "kind": "timeout",
    "code": "evalTimeout",
    "message": "Eval timed out after 10000 ms.",
    "retryable": false
  },
  "final": true
}

JSON Schema

{
  "type": "object",
  "required": [
    "type",
    "id",
    "seq",
    "error",
    "final"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "subscribe_error"
    },
    "id": {
      "type": "string"
    },
    "seq": {
      "type": "number"
    },
    "error": {
      "type": "object",
      "required": [
        "kind",
        "code",
        "message",
        "retryable"
      ],
      "properties": {
        "kind": {
          "anyOf": [
            {
              "type": "string",
              "const": "validation_failed"
            },
            {
              "type": "string",
              "const": "precondition_failed"
            },
            {
              "type": "string",
              "const": "conflict"
            },
            {
              "type": "string",
              "const": "timeout"
            },
            {
              "type": "string",
              "const": "cancelled"
            },
            {
              "type": "string",
              "const": "busy"
            },
            {
              "type": "string",
              "const": "unknown_command"
            },
            {
              "type": "string",
              "const": "unsupported_operation"
            },
            {
              "type": "string",
              "const": "artifact_missing"
            },
            {
              "type": "string",
              "const": "invalid_request"
            },
            {
              "type": "string",
              "const": "internal"
            }
          ]
        },
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "retryable": {
          "type": "boolean"
        },
        "details": {}
      },
      "additionalProperties": false
    },
    "final": {
      "type": "boolean"
    }
  },
  "additionalProperties": false
}

cancel C→S v2

Cancel an active eval or subscription by its request id. Not yet sent by the TypeScript SDK RuntimeRequest; available for custom transports.

Example

{ "type": "cancel", "id": "cancel-1", "targetId": "watch-1" }

JSON Schema

{
  "type": "object",
  "required": [
    "type",
    "id",
    "targetId"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "cancel"
    },
    "id": {
      "type": "string"
    },
    "targetId": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

Typed Commands

Schema-validated operations registered by the host.

commands_list C→S v2

List all commands currently registered by the host.

Example

{ "type": "commands_list", "id": "list-1" }

JSON Schema

{
  "type": "object",
  "required": [
    "type",
    "id"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "commands_list"
    },
    "id": {
      "type": "string"
    },
    "since": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

commands_list_result S→C v2

The full command catalog.

Example

{
  "type": "commands_list_result",
  "id": "list-1",
  "commands": [
    { "name": "archive.preflight", "majorVersion": 1, "kind": "sync", "mutatesState": false },
    { "name": "archive.export", "majorVersion": 1, "kind": "job", "mutatesState": true }
  ]
}

JSON Schema

{
  "type": "object",
  "required": [
    "type",
    "id",
    "commands"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "commands_list_result"
    },
    "id": {
      "type": "string"
    },
    "commands": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "name",
          "majorVersion",
          "kind",
          "mutatesState"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "majorVersion": {
            "type": "number"
          },
          "kind": {
            "anyOf": [
              {
                "type": "string",
                "const": "sync"
              },
              {
                "type": "string",
                "const": "job"
              }
            ]
          },
          "mutatesState": {
            "type": "boolean"
          }
        },
        "additionalProperties": false
      }
    },
    "since": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

command_describe C→S v2

Fetch the full descriptor for one command, including I/O schemas.

Example

{ "type": "command_describe", "id": "describe-1", "name": "archive.preflight" }

JSON Schema

{
  "type": "object",
  "required": [
    "type",
    "id",
    "name"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "command_describe"
    },
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

command_describe_result S→C v2

Full command descriptor including JSON schemas for input, output, and artifacts.

Example

{
  "type": "command_describe_result",
  "id": "describe-1",
  "descriptor": {
    "name": "archive.preflight",
    "majorVersion": 1,
    "kind": "sync",
    "mutatesState": false,
    "inputSchema": { "type": "object", "properties": {} },
    "outputSchema": { "type": "object", "properties": { "ok": { "type": "boolean" } } },
    "artifactsSchema": { "type": "object" }
  }
}

JSON Schema

{
  "type": "object",
  "required": [
    "type",
    "id",
    "descriptor"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "command_describe_result"
    },
    "id": {
      "type": "string"
    },
    "descriptor": {
      "type": "object",
      "required": [
        "name",
        "majorVersion",
        "kind",
        "mutatesState",
        "inputSchema",
        "outputSchema",
        "artifactsSchema"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "majorVersion": {
          "type": "number"
        },
        "kind": {
          "anyOf": [
            {
              "type": "string",
              "const": "sync"
            },
            {
              "type": "string",
              "const": "job"
            }
          ]
        },
        "mutatesState": {
          "type": "boolean"
        },
        "inputSchema": {
          "type": "object",
          "patternProperties": {
            "^.*$": {}
          }
        },
        "outputSchema": {
          "type": "object",
          "patternProperties": {
            "^.*$": {}
          }
        },
        "artifactsSchema": {
          "type": "object",
          "patternProperties": {
            "^.*$": {}
          }
        },
        "cancellation": {
          "type": "string"
        }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}

command_call C→S v2

Execute a registered command. args must be a JSON object.

Example

{ "type": "command_call", "id": "cmd-1", "name": "archive.preflight", "args": {} }

JSON Schema

{
  "type": "object",
  "required": [
    "type",
    "id",
    "name",
    "args"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "command_call"
    },
    "id": {
      "type": "string"
    },
    "name": {
      "type": "string"
    },
    "args": {
      "type": "object",
      "patternProperties": {
        "^.*$": {}
      }
    },
    "timeoutMs": {
      "type": "number"
    }
  },
  "additionalProperties": false
}

command_result S→C v2

Result for synchronous commands and failed jobs. status ok or failed; error present on failure.

Example

{
  "type": "command_result",
  "id": "cmd-1",
  "status": "ok",
  "output": { "ok": true },
  "artifacts": {},
  "durationMs": 12
}

JSON Schema

{
  "type": "object",
  "required": [
    "type",
    "id",
    "status",
    "artifacts",
    "durationMs"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "command_result"
    },
    "id": {
      "type": "string"
    },
    "status": {
      "anyOf": [
        {
          "type": "string",
          "const": "ok"
        },
        {
          "type": "string",
          "const": "failed"
        }
      ]
    },
    "output": {},
    "artifacts": {
      "type": "object",
      "patternProperties": {
        "^.*$": {
          "type": "object",
          "required": [
            "uri",
            "sha256",
            "byteSize",
            "contentType",
            "finalized"
          ],
          "properties": {
            "uri": {
              "type": "string"
            },
            "path": {
              "type": "string"
            },
            "sha256": {
              "type": "string"
            },
            "byteSize": {
              "type": "number"
            },
            "contentType": {
              "type": "string"
            },
            "finalized": {
              "type": "boolean"
            }
          },
          "additionalProperties": false
        }
      }
    },
    "error": {
      "type": "object",
      "required": [
        "kind",
        "code",
        "message",
        "retryable"
      ],
      "properties": {
        "kind": {
          "anyOf": [
            {
              "type": "string",
              "const": "validation_failed"
            },
            {
              "type": "string",
              "const": "precondition_failed"
            },
            {
              "type": "string",
              "const": "conflict"
            },
            {
              "type": "string",
              "const": "timeout"
            },
            {
              "type": "string",
              "const": "cancelled"
            },
            {
              "type": "string",
              "const": "busy"
            },
            {
              "type": "string",
              "const": "unknown_command"
            },
            {
              "type": "string",
              "const": "unsupported_operation"
            },
            {
              "type": "string",
              "const": "artifact_missing"
            },
            {
              "type": "string",
              "const": "invalid_request"
            },
            {
              "type": "string",
              "const": "internal"
            }
          ]
        },
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "retryable": {
          "type": "boolean"
        },
        "details": {}
      },
      "additionalProperties": false
    },
    "durationMs": {
      "type": "number"
    }
  },
  "additionalProperties": false
}

Jobs

Long-running async commands polled by the client.

job_accepted S→C v2

A job command was accepted and is now running. Poll with job_status.

Example

{ "type": "job_accepted", "id": "cmd-1", "jobId": "job-1", "state": "running" }

JSON Schema

{
  "type": "object",
  "required": [
    "type",
    "id",
    "jobId",
    "state"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "job_accepted"
    },
    "id": {
      "type": "string"
    },
    "jobId": {
      "type": "string"
    },
    "state": {
      "type": "string",
      "const": "running"
    }
  },
  "additionalProperties": false
}

job_status C→S v2

Poll a running job for progress or terminal result.

Example

{ "type": "job_status", "id": "status-1", "jobId": "job-1" }

JSON Schema

{
  "type": "object",
  "required": [
    "type",
    "id",
    "jobId"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "job_status"
    },
    "id": {
      "type": "string"
    },
    "jobId": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

job_status_result S→C v2

Job is still running. Continue polling.

Example

{ "type": "job_status_result", "id": "status-1", "jobId": "job-1", "state": "running" }

JSON Schema

{
  "type": "object",
  "required": [
    "type",
    "id",
    "jobId",
    "state"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "job_status_result"
    },
    "id": {
      "type": "string"
    },
    "jobId": {
      "type": "string"
    },
    "state": {
      "type": "string",
      "const": "running"
    },
    "progress": {},
    "error": {
      "type": "object",
      "required": [
        "kind",
        "code",
        "message",
        "retryable"
      ],
      "properties": {
        "kind": {
          "anyOf": [
            {
              "type": "string",
              "const": "validation_failed"
            },
            {
              "type": "string",
              "const": "precondition_failed"
            },
            {
              "type": "string",
              "const": "conflict"
            },
            {
              "type": "string",
              "const": "timeout"
            },
            {
              "type": "string",
              "const": "cancelled"
            },
            {
              "type": "string",
              "const": "busy"
            },
            {
              "type": "string",
              "const": "unknown_command"
            },
            {
              "type": "string",
              "const": "unsupported_operation"
            },
            {
              "type": "string",
              "const": "artifact_missing"
            },
            {
              "type": "string",
              "const": "invalid_request"
            },
            {
              "type": "string",
              "const": "internal"
            }
          ]
        },
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "retryable": {
          "type": "boolean"
        },
        "details": {}
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}

job_result S→C v2

Terminal job result. Returned in place of job_status_result once the job is done, failed, or cancelled.

Example

{
  "type": "job_result",
  "id": "status-2",
  "jobId": "job-1",
  "state": "done",
  "status": "ok",
  "output": { "itemsExported": 1500 },
  "artifacts": {},
  "durationMs": 1842
}

JSON Schema

{
  "type": "object",
  "required": [
    "type",
    "id",
    "jobId",
    "state",
    "status",
    "artifacts",
    "durationMs"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "job_result"
    },
    "id": {
      "type": "string"
    },
    "jobId": {
      "type": "string"
    },
    "state": {
      "anyOf": [
        {
          "type": "string",
          "const": "done"
        },
        {
          "type": "string",
          "const": "failed"
        },
        {
          "type": "string",
          "const": "cancelled"
        }
      ]
    },
    "status": {
      "anyOf": [
        {
          "type": "string",
          "const": "ok"
        },
        {
          "type": "string",
          "const": "failed"
        }
      ]
    },
    "output": {},
    "artifacts": {
      "type": "object",
      "patternProperties": {
        "^.*$": {
          "type": "object",
          "required": [
            "uri",
            "sha256",
            "byteSize",
            "contentType",
            "finalized"
          ],
          "properties": {
            "uri": {
              "type": "string"
            },
            "path": {
              "type": "string"
            },
            "sha256": {
              "type": "string"
            },
            "byteSize": {
              "type": "number"
            },
            "contentType": {
              "type": "string"
            },
            "finalized": {
              "type": "boolean"
            }
          },
          "additionalProperties": false
        }
      }
    },
    "error": {
      "type": "object",
      "required": [
        "kind",
        "code",
        "message",
        "retryable"
      ],
      "properties": {
        "kind": {
          "anyOf": [
            {
              "type": "string",
              "const": "validation_failed"
            },
            {
              "type": "string",
              "const": "precondition_failed"
            },
            {
              "type": "string",
              "const": "conflict"
            },
            {
              "type": "string",
              "const": "timeout"
            },
            {
              "type": "string",
              "const": "cancelled"
            },
            {
              "type": "string",
              "const": "busy"
            },
            {
              "type": "string",
              "const": "unknown_command"
            },
            {
              "type": "string",
              "const": "unsupported_operation"
            },
            {
              "type": "string",
              "const": "artifact_missing"
            },
            {
              "type": "string",
              "const": "invalid_request"
            },
            {
              "type": "string",
              "const": "internal"
            }
          ]
        },
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "retryable": {
          "type": "boolean"
        },
        "details": {}
      },
      "additionalProperties": false
    },
    "durationMs": {
      "type": "number"
    }
  },
  "additionalProperties": false
}

job_cancel C→S v2

Request cancellation of a running job.

Example

{ "type": "job_cancel", "id": "jc-1", "jobId": "job-1" }

JSON Schema

{
  "type": "object",
  "required": [
    "type",
    "id",
    "jobId"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "job_cancel"
    },
    "id": {
      "type": "string"
    },
    "jobId": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

job_cancel_result S→C v2

Cancellation acknowledgement. accepted indicates whether the runtime accepted the request.

Example

{ "type": "job_cancel_result", "id": "jc-1", "accepted": true, "state": "running" }

JSON Schema

{
  "type": "object",
  "required": [
    "type",
    "id",
    "accepted",
    "state"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "job_cancel_result"
    },
    "id": {
      "type": "string"
    },
    "accepted": {
      "type": "boolean"
    },
    "state": {
      "anyOf": [
        {
          "type": "string",
          "const": "running"
        },
        {
          "type": "string",
          "const": "done"
        },
        {
          "type": "string",
          "const": "failed"
        },
        {
          "type": "string",
          "const": "cancelled"
        }
      ]
    }
  },
  "additionalProperties": false
}

Journal

Queryable history of recent eval and command activity.

journal_query C→S v2

Query recent eval and command journal entries.

Example

{ "type": "journal_query", "id": "journal-1", "kind": "command", "limit": 20 }

JSON Schema

{
  "type": "object",
  "required": [
    "type",
    "id"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "journal_query"
    },
    "id": {
      "type": "string"
    },
    "kind": {
      "anyOf": [
        {
          "type": "string",
          "const": "eval"
        },
        {
          "type": "string",
          "const": "command"
        }
      ]
    },
    "limit": {
      "type": "number"
    }
  },
  "additionalProperties": false
}

journal_query_result S→C v2

Recent journal entries, newest first.

Example

{
  "type": "journal_query_result",
  "id": "journal-1",
  "entries": [
    {
      "id": "cmd-1",
      "kind": "command",
      "name": "archive.preflight",
      "success": true,
      "durationMs": 12,
      "timestamp": "2026-05-23T12:00:00.000Z"
    }
  ]
}

JSON Schema

{
  "type": "object",
  "required": [
    "type",
    "id",
    "entries"
  ],
  "properties": {
    "type": {
      "type": "string",
      "const": "journal_query_result"
    },
    "id": {
      "type": "string"
    },
    "entries": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "id",
          "kind",
          "success",
          "durationMs",
          "timestamp"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "kind": {
            "anyOf": [
              {
                "type": "string",
                "const": "eval"
              },
              {
                "type": "string",
                "const": "command"
              }
            ]
          },
          "name": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "success": {
            "type": "boolean"
          },
          "durationMs": {
            "type": "number"
          },
          "errorKind": {
            "anyOf": [
              {
                "type": "string",
                "const": "validation_failed"
              },
              {
                "type": "string",
                "const": "precondition_failed"
              },
              {
                "type": "string",
                "const": "conflict"
              },
              {
                "type": "string",
                "const": "timeout"
              },
              {
                "type": "string",
                "const": "cancelled"
              },
              {
                "type": "string",
                "const": "busy"
              },
              {
                "type": "string",
                "const": "unknown_command"
              },
              {
                "type": "string",
                "const": "unsupported_operation"
              },
              {
                "type": "string",
                "const": "artifact_missing"
              },
              {
                "type": "string",
                "const": "invalid_request"
              },
              {
                "type": "string",
                "const": "internal"
              }
            ]
          },
          "timestamp": {
            "type": "string"
          }
        },
        "additionalProperties": false
      }
    }
  },
  "additionalProperties": false
}

Shared Types

Reusable structures referenced by multiple messages.

ErrorEnvelope

Unified error representation used in every failure response.

Example

{
  "kind": "validation_failed",
  "code": "badArgument",
  "message": "The command argument is invalid.",
  "retryable": false,
  "details": { "path": "/scene" }
}

JSON Schema

{
  "type": "object",
  "required": [
    "kind",
    "code",
    "message",
    "retryable"
  ],
  "properties": {
    "kind": {
      "anyOf": [
        {
          "type": "string",
          "const": "validation_failed"
        },
        {
          "type": "string",
          "const": "precondition_failed"
        },
        {
          "type": "string",
          "const": "conflict"
        },
        {
          "type": "string",
          "const": "timeout"
        },
        {
          "type": "string",
          "const": "cancelled"
        },
        {
          "type": "string",
          "const": "busy"
        },
        {
          "type": "string",
          "const": "unknown_command"
        },
        {
          "type": "string",
          "const": "unsupported_operation"
        },
        {
          "type": "string",
          "const": "artifact_missing"
        },
        {
          "type": "string",
          "const": "invalid_request"
        },
        {
          "type": "string",
          "const": "internal"
        }
      ]
    },
    "code": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "retryable": {
      "type": "boolean"
    },
    "details": {}
  },
  "additionalProperties": false
}

ArtifactRef

Named reference to a file produced by a command. Consumers must verify sha256 before trusting content.

Example

{
  "uri": "file:///exports/items.json",
  "path": "/exports/items.json",
  "sha256": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b",
  "byteSize": 48392,
  "contentType": "application/json",
  "finalized": true
}

JSON Schema

{
  "type": "object",
  "required": [
    "uri",
    "sha256",
    "byteSize",
    "contentType",
    "finalized"
  ],
  "properties": {
    "uri": {
      "type": "string"
    },
    "path": {
      "type": "string"
    },
    "sha256": {
      "type": "string"
    },
    "byteSize": {
      "type": "number"
    },
    "contentType": {
      "type": "string"
    },
    "finalized": {
      "type": "boolean"
    }
  },
  "additionalProperties": false
}

CommandDescriptor

Full metadata for a registered typed command including JSON schemas for its input and output.

Example

{
  "name": "archive.preflight",
  "majorVersion": 1,
  "kind": "sync",
  "mutatesState": false,
  "inputSchema": { "type": "object", "properties": {} },
  "outputSchema": { "type": "object", "properties": { "ok": { "type": "boolean" } } },
  "artifactsSchema": { "type": "object" }
}

JSON Schema

{
  "type": "object",
  "required": [
    "name",
    "majorVersion",
    "kind",
    "mutatesState",
    "inputSchema",
    "outputSchema",
    "artifactsSchema"
  ],
  "properties": {
    "name": {
      "type": "string"
    },
    "majorVersion": {
      "type": "number"
    },
    "kind": {
      "anyOf": [
        {
          "type": "string",
          "const": "sync"
        },
        {
          "type": "string",
          "const": "job"
        }
      ]
    },
    "mutatesState": {
      "type": "boolean"
    },
    "inputSchema": {
      "type": "object",
      "patternProperties": {
        "^.*$": {}
      }
    },
    "outputSchema": {
      "type": "object",
      "patternProperties": {
        "^.*$": {}
      }
    },
    "artifactsSchema": {
      "type": "object",
      "patternProperties": {
        "^.*$": {}
      }
    },
    "cancellation": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

JournalEntry

One record in the eval/command history.

Example

{
  "id": "eval-1",
  "kind": "eval",
  "code": "1 + 1",
  "success": true,
  "durationMs": 3,
  "timestamp": "2026-05-23T12:00:00.000Z"
}

JSON Schema

{
  "type": "object",
  "required": [
    "id",
    "kind",
    "success",
    "durationMs",
    "timestamp"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "kind": {
      "anyOf": [
        {
          "type": "string",
          "const": "eval"
        },
        {
          "type": "string",
          "const": "command"
        }
      ]
    },
    "name": {
      "type": "string"
    },
    "code": {
      "type": "string"
    },
    "success": {
      "type": "boolean"
    },
    "durationMs": {
      "type": "number"
    },
    "errorKind": {
      "anyOf": [
        {
          "type": "string",
          "const": "validation_failed"
        },
        {
          "type": "string",
          "const": "precondition_failed"
        },
        {
          "type": "string",
          "const": "conflict"
        },
        {
          "type": "string",
          "const": "timeout"
        },
        {
          "type": "string",
          "const": "cancelled"
        },
        {
          "type": "string",
          "const": "busy"
        },
        {
          "type": "string",
          "const": "unknown_command"
        },
        {
          "type": "string",
          "const": "unsupported_operation"
        },
        {
          "type": "string",
          "const": "artifact_missing"
        },
        {
          "type": "string",
          "const": "invalid_request"
        },
        {
          "type": "string",
          "const": "internal"
        }
      ]
    },
    "timestamp": {
      "type": "string"
    }
  },
  "additionalProperties": false
}