Crate vagus_plugin_protocol 

Wire schema for the vagus plugin contract — the language-agnostic protocol a vagus-<name> plugin speaks back to vagus core over stdout.

This crate is intentionally tiny and dependency-light (serde only). It is shared by both vagus core (which parses the events) and the vagus-plugin SDK (which emits them) so the on-the-wire shape can never drift between the two. Non-Rust plugins ignore this crate and just emit the documented JSON; see docs/plugin-contract.md.

The contract in one paragraph

Core spawns vagus-<name> as a child with the subcommand name stripped from argv, stdin/stderr inherited, stdout piped, and the env vars set. The plugin streams newline-delimited JSON Events on stdout (machine channel) and writes human logs to stderr. Any stdout line that does not parse as a known Event is echoed verbatim by core (so trivial text-only plugins still work). On a clean exit, core indexes every Event::Note path it saw.

Enums

Event

One newline-delimited JSON record on a plugin’s stdout. Externally tagged on type.

LogLevel

Severity for a Event::Log.

NoteAction

What happened to a note file, so core knows whether to (re)index or drop it.

Constants

CONTRACT_VERSION

Contract version core advertises via ENV_CONTRACT. Bumped only on breaking changes; the event schema is otherwise extended additively (new optional fields, new #[serde(other)]-tolerated variants), so a plugin built against v1 keeps working.

DESCRIBE_SUBCOMMAND

Reserved discovery subcommand: vagus-<name> __describe prints a one-line summary on stdout for vagus plugins. Used by both core (caller) and the SDK (callee).

ENV_CONFIG_DIR

vagus config dir — informational.

ENV_CONTRACT

Decimal CONTRACT_VERSION core supports, for additive compat checks by the plugin.

ENV_DATA_DIR

vagus data dir (~/.local/share/vagus) — informational; plugins keep their own state under their own XDG dir, never here and never in the vault.

ENV_PROTOCOL

Set to PROTOCOL_NDJSON when core is the parent and wants the NDJSON event stream. When unset, the plugin was run standalone (directly, not via vagus) and should print human output and self-index via $VAGUS index.

ENV_VAGUS_BIN

Absolute path to the vagus binary, so a plugin can call back (e.g. $VAGUS index) without guessing where core lives. Set by core for every plugin invocation.

ENV_VAULT

Absolute path to the resolved vault root (the ~/brain symlink target). Plugins write Markdown here and must not write anything else (guardrail G1/G16).

ENV_VERSION

Core’s version string.

PROTOCOL_NDJSON

The only protocol value currently defined for ENV_PROTOCOL.