VTX 1 · core · beta draft d03
VTX 1 Wire Specification: core
§17Application interface
Applications do not speak the wire protocol. The server runs the application and talks to it in the text form: one JSON object per line, UTF-8 (JSON Lines). The server turns the application's ops into UPDATE frames and the client's input into lines for the application. A program that prints JSON, or an AI agent's tool runtime, can drive a VTX session this way. A server decides per application whether it uses this interface or runs the application under the VT engine (Section 8).
Transports.
- stdio. The server starts the application with standard input and output as the stream; standard error goes to the server's log.
- WebSocket. Subprotocol
vtx-app1(vtx-app1-d03in draft d03), one line per text message, for applications that run elsewhere, such as an agent service. Which side connects, and how it authenticates (mutual TLS or a bearer token, for example), is the deployment's choice.
Lines from the application (vtx-app-1.schema.json). A line with op is a scene op (Section 7). Ops between begin and commit form one update; any other op is an update of its own. A begin without commit is discarded after 30 seconds or when the stream closes. A line without op is a control line, named by its kind (some ops, such as chart and input, have a kind prop of their own):
| Kind | Purpose |
|---|---|
approval |
Ask the user to approve a request in the trusted zone (Section 12); answered by zone_result |
permission |
Ask for a permission (Section 12); answered by zone_result |
claim |
Set the name, icon and colour the trusted zone shows for the application (CLAIM) |
cancel |
Withdraw a pending approval, permission or clipboard read by id |
clipboard_write |
Write to the user's clipboard (Section 13) |
clipboard_read |
Ask to read the clipboard; answered by clipboard_data |
haptic |
Play a haptic effect on an input device (Section 11) |
resource |
Provide a glyph or font as base64 with its format and hash; the server checks the hash, then offers and serves it (Section 10) |
end |
End the session, with an optional exit status |
Lines to the application (vtx-app-events-1.schema.json), all with kind:
| Kind | Carries |
|---|---|
session |
attached, detached, resumed, display, caps, locale or ended, with the user, sign-in method, certificate (for x509 and tls-cert), locale, time zone, Unicode version, accepted capabilities, display and input devices as they apply |
intent |
An INTENT, after the server has joined its parts and dropped duplicates (Section 6) |
input |
Any other input event: event names it (key, pointer, resize and so on) and data holds the frame's payload |
scene_error |
An op that failed: the error code with the op's state and index, or parse with the line number |
zone_result |
The answer to an approval or permission: decision, the request digest and, for uv, the WebAuthn assertion or the card signature |
clipboard_data |
The answer to clipboard_read, or denied |
Rules.
- The server validates every line. An invalid op is not sent and produces
scene_error; so does a line that is not JSON, withcode: "parse"and its line number. - The server numbers states, splits large updates, and handles credit, acknowledgement, retention and resume. The application sees one continuous session.
- The server checks approval digests and assertions before
zone_resultreaches the application, and passes on the assertion so the application can keep it with the request and its origin (Section 12). - An application that closes its output ends the session as
endwould, without an exit status.