Backplane Plugin Protocol

Standalone Agent Plugins 1.0.0 package inspection and Backplane distribution client. No Repo, Phoenix, application supervisor, process execution, filesystem installation, credential storage or network adapter is required.

{:ok, package} = Backplane.PluginProtocol.load(%{
  "plugin.json" => JSON.encode!(%{
    "$schema" => "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
    "name" => "example"
  })
})

{:ok, package} = Backplane.PluginProtocol.load_directory("/path/to/example")
{:ok, artifact} = Backplane.PluginProtocol.Archive.pack(package.files)
digest = Backplane.PluginProtocol.Archive.digest(artifact)

load/2 returns {:ok, package} or {:error, diagnostics}. Package fields:

manifest: original JSON object, including unknown fields and extensions. Unknown fields are reported and ignored for interpretation; original bytes stay in files. Missing version and arbitrary version strings are supported.
skills: immediate skills/*/SKILL.md entries with path, root, name, description, raw content, Markdown body, YAML metadata, and resource files keyed by their full package-relative paths.
mcp_servers: server-name map of validated raw string-key configurations. Types are stdio, streamable-http, and optional legacy sse.
diagnostics: %{severity: :error | :warning, code: atom, path: string, message: string}. Component errors can appear in a successful package.
files: the complete original relative-path-to-binary snapshot.

Manifest errors reject the package, except unknown top-level fields and non-object extensions. Unimplemented extension values are not validated. Invalid individual skills or MCP servers are skipped. Invalid mcp.json disables only MCP. Schemas are bundled as references; loading selects locally implemented rules and never downloads a schema. transports: ["stdio", "streamable-http"] restricts discovery to supported transports, with diagnostics for skipped transports.

MCP values remain unexpanded. Runtime hosts must expand only ${PLUGIN_ROOT} and ${PLUGIN_DATA}, once, in args/env values/cwd; provide both reserved variables; recheck resolved command/cwd containment; enforce HTTP origin and header rules; and handle connection failures per server. The loader validates reserved env names, token commands, cwd containment, HTTPS/loopback URLs and HTTP headers. Arguments and environment values remain opaque, including unknown placeholders.

Snapshots and safety

Archive.pack/2, unpack/2, digest/1, and read_directory/2 are shared by publishers and installers. Archives use sorted deterministic USTAR in gzip, fixed uid/gid/mtime, and regular files with 0644 default permissions. pack(files, modes: %{relative_path => 0o755}) preserves executable resources. unpack_with_metadata/2 and read_directory_with_metadata/2 return {:ok, %{files: files, modes: modes}}, preserving low permission bits only; privileged setuid/setgid/sticky bits are never retained. File maps alone carry bytes, so publishers and installers should use the metadata APIs. Paths that cannot fit USTAR name/prefix fields fail packing. Unpacking accepts USTAR regular files and directories, ignores empty directories, and rejects links, special files, PAX/GNU extensions, duplicates, invalid checksums, absolute paths, traversal, Windows separators/drive prefixes, file/directory conflicts and trailing nonzero data. Decoding happens in memory and never extracts filesystem paths.

Defaults: 32 MiB compressed, 80 MB decompressed tar, 64 MiB total file bytes, 16 MiB per file, 10,000 files, 20,000 entries and 64 filesystem levels. Override with max_archive_bytes, max_uncompressed_bytes, max_total_bytes, max_file_bytes, max_files, max_entries, max_depth. Strict Archive directory readers reject all links and special files. PluginProtocol.load_directory/2 instead resolves safe links within the filesystem-resolved plugin root, retaining their target bytes under the original package-relative alias paths. An escaping manifest rejects the plugin; an escaping fixed component location disables that component, an escaping skill document skips that skill, and other escaping resources are omitted with diagnostics. Link and directory cycles are denied. The file-map and archive snapshot APIs remain unchanged. Callers must keep the directory stable during reads; these APIs are not an OS sandbox against concurrent hostile filesystem mutation.

Distribution client

client = Backplane.PluginProtocol.Client.new(
  base_url: "https://backplane.example",
  auth: access_token,
  transport: fn request -> MyHTTP.request(request) end
)
{:ok, catalog} = Backplane.PluginProtocol.Client.catalog(client)
{:ok, release} = Backplane.PluginProtocol.Client.resolve(client,
  plugin_id: plugin_id, channel: "stable")
{:ok, download} = Backplane.PluginProtocol.Client.download(client,
  release["artifact_digest"])

Transport accepts %{method: method, url: string, headers: pairs, body: nil | binary} and returns {:ok, %{status: integer, body: binary | map}} | {:error, reason}. It must enforce TLS, timeouts, response limits, cancellation and safe redirect policy. auth also accepts a zero-arity header provider; headers supplies extra pairs. Catalog and resolve return the decoded API object. Download checks the exact SHA-256 before unpacking/loading, then returns %{artifact, artifact_digest, files, modes, package}. HTTP failures return {:error, {:http_status, status}} without exposing raw provider bodies. Endpoints are /plugin-protocol/v1/catalog, /resolve (GET query: plugin_id/release_id/channel), and /artifacts/:digest. This is Backplane's API, not an official Agent Plugins registry protocol. Client.request(client, method, path, body \\ nil) makes a JSON request under the same prefix for installation listing/reporting. path starts with / and cannot contain traversal, a query or an alternate origin. A supplied body is JSON-encoded with content-type: application/json; responses are decoded objects.

Specification references, checked 2026-10-23: