Plugin protocol
Handshake, capabilities, view updates and errors in sysc-shell plugin/v1.
The SDK in sysc-shell/plugin/v1 defines the Go types for the wire protocol. The wire format remains JSON Lines over stdin and stdout, so a plugin written in another language can implement the same messages.
Plugin handshake
The host sends host.hello as the first message. It lists supported protocol versions, the plugin identity, capability grants and message limits. The plugin responds with plugin.hello, including its identity and selected version. Client.Handshake reads the first message, chooses the highest common protocol v1 minor and sends the response.
The helper returns an error if the first message is not host.hello or the host advertises no compatible v1 version. Stop startup on that error. Keep the ID, name and version consistent with the manifest. Do not write logs or banners to stdout; send diagnostics to stderr so they cannot corrupt the message stream.
Host capabilities
The host sends only capabilities it grants after intersecting the plugin's request with host support. Check the returned grants before using host APIs. A call can fail because a capability or resource is unavailable; inspect both the Go error and HostReply.Error, and use a deadline when waiting for a reply.
Capabilities limit calls through the host API. They do not sandbox the plugin process. The executable can still access files, processes and network resources allowed to the same user.
View lifecycle
The host opens a view with view.open and assigns its view_id, view kind and available dimensions. Send a view.snapshot with a new revision. A view.patch names the base revision it replaces. On view.resync, send a fresh snapshot. Handle view.close without stopping the process if other views remain. On host.shutdown, release resources and exit.
If the handshake fails, a message is malformed, a call returns an error or the host rejects a view, report enough context on stderr for the user to diagnose the problem. The host can replace a rejected view with its failure card while the plugin process continues.
See the SDK's Client and message.go for the exact API at the recorded source revision.