Crate turbovault_plugin_api

Expand description

Stable contracts for compiled-in TurboVault plugins.

This crate is intentionally smaller than TurboVault’s internal API. A plugin receives a curated VaultApi facade and an advisory HookBus, never a raw vault manager or MCP server.

Plugins are compiled into the host behind default-off Cargo features. The host mounts each plugin under PluginDescriptor::id and namespaces all three MCP primitives, so in the tasks plugin a local tool list is advertised as tasks_list, a prompt review as tasks_review, and a resource index/stats.json as tasks://index/stats.json. A plugin names only the local half.

§Trust model

Plugins are statically linked into the TurboVault process. This API is a contract, not a sandbox. A compiled-in plugin runs with the host’s full privileges: it can open files, spawn threads, and reach the network regardless of what it declares here. The boundary exists to keep plugins decoupled from TurboVault’s internals, to make what a plugin touches reviewable, and to stop accidental over-reach — not to contain hostile code. Only compile in plugins you would accept as a dependency.

Within that model the host does enforce real invariants: capabilities are per-plugin and declared up front, writes carry mandatory preconditions, event attribution is host-stamped, and a plugin’s tool calls are bounded in time and isolated from panics.

§Compatibility

Public types are #[non_exhaustive] and built through constructors and builder setters, so this crate can gain fields, variants, and trait methods (always with defaults) without a breaking release. Construct types via their new functions rather than struct literals.

Structs§

Completion: Suggested values for one argument.
CompletionRequest: A request to suggest values for an argument a user is part-way through.
EventCursor: A consumer’s durable position in the event feed.
HookBus: Cloneable bounded event bus shared by a host and its plugins.
HookSubscription: A single bounded subscription to HookBus.
NoteListing: A note’s identity and change-detection metadata, without its content.
NoteSnapshot: A note plus the backend-native version token used for safe writes.
PluginCapabilities: What a plugin declares it needs beyond the note APIs.
PluginContext: Capabilities provided to a plugin when it is constructed.
PluginDescriptor: Stable identity and compatibility metadata for a compiled-in plugin.
PluginError: Error type shared by the host and plugins.
PluginIdentity: The calling plugin’s namespace and what it declared it needs.
PluginRequestContext: Curated request data passed to plugin tool calls.
PluginStorage: Durable, plugin-private, per-vault key/value storage.
Prompt: Prompt definition.
PromptResult: Result from getting a prompt.
Resource: Resource definition.
ResourceResult: Result from reading a resource.
ResourceTemplate: Resource template definition.
ShutdownSignal: Cooperative shutdown signal handed to a plugin’s background work.
ShutdownTrigger: Host-side handle that requests shutdown.
Tool: Tool definition.
ToolResult: Result from calling a tool.
VaultApi: Cloneable, curated facade supplied to every plugin.
VaultDescriptor: Public identity of a vault the host has registered.
VaultEventEnvelope: Sequenced event delivered to hook subscribers.
WriteNoteRequest: Safe full-note write request.
WriteProvenance: Provenance supplied by a writer for best-effort event correlation.
WriteReceipt: Result of a successful plugin write.

Enums§

CompletionTarget: What a completion request is asking a plugin to complete.
EventAttribution: Best-effort event attribution.
HookEvent: A vault mutation observed by a hook producer.
HookLifecycle: Current event-bus lifecycle.
HookRecvError: Receive failure with explicit overflow semantics.
PluginErrorCode: Stable, machine-readable categories returned across the plugin boundary.
PublishError: Publish failure.
WritePrecondition: Required optimistic-concurrency condition for a plugin write.

Constants§

MCP_TOOL_NAME_MAX_LEN: Maximum tool-name length recommended by MCP SEP-986.

Traits§

Plugin: Factory contract for a compiled-in plugin.
PluginProvider: Object-safe MCP tool provider implemented by a plugin.
PluginStore: Host implementation behind PluginStorage.
VaultHost: Host implementation behind VaultApi.

Functions§

namespaced_prompt_name: Build and validate the public MCP name for a plugin-local prompt.
namespaced_resource_template: Build and validate the public URI template for a plugin-local resource template.
namespaced_resource_uri: Build and validate the public URI for a plugin-local resource.
namespaced_tool_name: Build and validate the public MCP name for a plugin-local tool.
validate_mcp_tool_name: Validate a complete tool name against MCP SEP-986.
validate_plugin_id: Validate a plugin namespace.

Type Aliases§

PluginResult: Result type used by plugin contracts.