RFC 0005: Runtime Tool Plugin Protocol

• Status: draft
• Initial package: plugin/v1
• Transport: one local gRPC connection per process generation

Purpose

Runtime plugins support tools whose executable implementation is not part of the compiled application. They are the only dynamic extension graph. The protocol does not recreate static Spice composition and never registers compiled stages, providers, or native UI code.

Identity and launch

Configuration includes a canonical absolute executable path, expected SHA-256, plugin name, startup/call/drain bounds, and approved capabilities. The host opens the verified file, detects path/digest drift as far as the operating system permits, launches with a random single-use handshake secret, and bounds stderr. PATH lookup and ambient directory scanning are forbidden.

Initialize exchanges protocol/build identity, manifest, tool definitions, capabilities, limits, and the launch-secret proof. A candidate is not visible to runs until all facts validate.

Generation lifecycle

Candidate activation is atomic and affects future runs only. Starting a run leases the current generation and snapshots its identity/tool definitions. Old processes remain alive until all leases release, then receive bounded drain and shutdown. A failed candidate or drain never mutates the active generation.

Host restart is bounded and applies only to future calls. A call interrupted by crash is failed. A mutating call with uncertain outcome is never automatically replayed. Cancellation propagates through RPC then process-tree cleanup; failure to confirm termination is observable.

Initial tool API

ListTools returns immutable bounded definitions. Execute accepts one validated call and streams bounded progress followed by exactly one result or typed failure. Call/progress IDs must match. Unknown capabilities, duplicate names, oversized schemas/payloads, post-terminal messages, and stdout protocol contamination fail the candidate or call according to phase.

Compatibility and language neutrality

Buf lint/breaking checks govern plugin/v1. Additive optional fields follow the engine-protocol rules. Go and Python 3.12+ fixtures must pass the same black-box conformance suite. Generated client code is permitted; importing host-private Go packages is not.

Trust model

Digest pinning provides provenance/change detection, not sandboxing. The process runs with the daemon user’s privileges unless a later launcher/policy extension provides real isolation. Capability declarations are mandatory metadata but not security theater: help/status must state whether an enforcing decorator exists.

Acceptance before freeze

Conformance covers wrong digest, path replacement, handshake replay, old/new versions, unknown fields, duplicate tools, malformed/oversized traffic, bounded stderr, crash at every lifecycle phase, cancellation, uncertain mutation, activation races, generation leases, drain timeout, and clean Windows/Unix process-tree shutdown.