plugin-system

Formerly rpc-plugin-system. The canonical repository is agents/plugin-system. The rename preserves existing v1 Go module/import paths, command names, configuration and runtime paths, protocol identifiers and release tags. The separate public SDK is part of the unreleased v2 work described below. See rename compatibility.

src/ is the source root. Workflow state is kept separately at repo root in workflow.toml and workflow/ so code, tests, and examples are not polluted by workflow bookkeeping. Project-level documentation lives in repo-root docs/. The substrate PRD, architecture, implementation spec, downstream provider guidance, compatibility notes, roadmap, v1 freeze notes, V2 requirement registry, V2 threat model, and V2 release admission gate are canonical docs under docs/.

Classic source layout:

• src/cmd/rpcplugind/ — daemon entrypoint.
• src/cmd/rpcplugin-init/ — Linux PID-namespace init/reaper for recovery-enabled system services.
• src/cmd/rpcpluginctl/ — CLI entrypoint.
• src/internal/adminrpc/ — local admin RPC server/client.
• src/internal/cli/ — CLI formatting helpers.
• src/internal/eventlog/ — JSONL event log writer/reader plus provider observability schema, filters, and redaction helpers.
• src/internal/kernel/ — plugin manager, host routing, lifecycle, monitoring.
• src/internal/runtime/ — runtime directory, sockets, executable and peercred helpers.
• src/internal/auth/ — startup token helpers.
• sdk/ — independently consumable v2 author SDK source, including structured diagnostics; stable v2 publication remains pending.
• src/pkg/plugin/ — compatibility facade for existing in-repo plugin imports.
• src/examples/ — example plugins.
• src/test/ — shared test fixtures/helpers.

Substrate boundary

This repo is the executable plugin substrate. It owns local process supervision, startup authentication, Unix-socket net/rpc transport, generation identity, lifecycle/heartbeat/restart behavior, routing, runtime artifacts, append-only JSONL logs, provider bundle metadata, SDK logging helpers, and local admin/CLI inspection.

Version boundaries are explicit:

• v1 is the frozen Linux-first local substrate and narrow routed-operation set;
• v2 adds dynamic lifecycle, trusted discovery/enrollment, signed replacement/upgrades, fenced remote execution, and the required external SDK/application-call contracts described below; and
• v3 is the Cross Platforms Proving Ground, requiring independent Linux, Windows, macOS, and FreeBSD admission with representative standalone consumers. OpenBSD and NetBSD are named extension targets with separate evidence.

The v3 contract is specified but not implemented by the current repository state. Compilation on an operating system is not platform admission.

It does not own broker admission, authority issuance, credential resolution, Lua execution, provider-specific workflow semantics, provider payload handling, or client-visible provider capability emission. Those belong to the core broker, authority owners, and provider-specific repos.

Provider observability is structured and redacted:

• provider diagnostics use the SDK/helper path, not arbitrary lifecycle log fields;
• plugin id, generation id, and pid are substrate-bound facts;
• capability id, operation id, correlation id, duration, bounded status, coarse error class, degraded/unavailable reason, counts/sizes, and non-authoritative digest facts are the safe diagnostic vocabulary;
• raw prompts, payloads, upstream response bodies, credentials, tokens, bearer strings, API keys, private keys, passwords, authority refs, handles, sockets, sessions, signer material, provider-private paths, and reusable external refs are rejected before durable provider writes or redacted before operator display.

Downstream provider docs should inherit this substrate by reference and add only provider-specific deltas. See docs/downstream-provider-guidance.md.

V2 application integration target

The application contract adds required v2 external host/plugin SDK packaging, versioned bounded application invocation and application-owned lifecycle/commit coordination. V2 is partly implemented, not released. The author SDK has been extracted into its own module; the complete authenticated application transport and durable acceptance path remain unfinished. Existing Heartbeat/Echo/Restart methods do not satisfy the application-call contract. Frozen v1 wire behavior remains unchanged.

The substrate authenticates, routes and supervises; applications authorize, validate domain results and commit their own state. Standalone consumer proof must cover failures, resource limits, pinned upgrades and stale result races. App payloads do not go through administrative RPC or Echo. The full v2 remote scope remains required; choosing local-only deployment does not waive producer release gates or make native v3 support available.

Provider diagnostics status

Final provider diagnostics judge sweep accepted this substrate with constraints. plugin-system owns the provider event schema, SDK helper, admin/CLI filters, and unsafe-material rejection/redaction. It still does not own provider-specific semantics, broker admission, authority issuance, routing policy, or client-visible provider surfaces. Keep provider diagnostics on Logger.ProviderDiagnostic; do not smuggle them through arbitrary lifecycle LogEvent fields.

Build all packages:

make build

Or directly from the source root:

cd src && go build ./...

Build command binaries directly from src/:

cd src
go build -buildvcs=false -o .tmp-bin/rpcplugin-init ./cmd/rpcplugin-init
go build -buildvcs=false -o .tmp-bin/rpcplugind ./cmd/rpcplugind
go build -buildvcs=false -o .tmp-bin/rpcpluginctl ./cmd/rpcpluginctl
go build -buildvcs=false -o .tmp-bin/rpcplugin-echo ./examples/rpcplugin-echo
go build -buildvcs=false -o .tmp-bin/rpcplugin-failure ./examples/rpcplugin-failure

Coverage policy:

• Every feature, issue fix, and regression fix must aim for 100% relevant test coverage of the behavior it touches.
• Relevant coverage means changed behavior, edge cases, regressions, and failure paths. It is not fake repository-wide line coverage theater.
• Any coverage gap must be recorded with reason, risk, and the smallest next coverage increment before the work can be considered done.
• Project coverage posture is tracked in workflow/artifacts/global-coverage-map.md.

Run the current package coverage report and write reusable evidence:

make coverage

The root coverage target checks both Go modules and writes separate reports:

• workflow/artifacts/coverage.out — producer (src/) Go coverage profile.
• workflow/artifacts/coverage-summary.txt — producer package coverage and function totals.
• workflow/artifacts/sdk-coverage.out — SDK (sdk/) Go coverage profile.
• workflow/artifacts/sdk-coverage-summary.txt — SDK package coverage and function totals.

Both summaries are printed. Producer-only coverage does not include SDK security/ fault-injection tests; neither summary is a combined repository total. Run go tool cover from the profile's owning module to inspect its source.

Run tests:

make test

Or explicitly from the repository root (preserving documentation checks):

make doc-check &&
(cd sdk && go test ./...) &&
(cd src && go test ./...)

make -C src test and make -C sdk test are module-local focused checks, not substitutes for the root entrypoint. A dependency-module replace does not make Go run that dependency's tests. Root make test and make coverage stop on a failed module command; the unchanged documentation checks gate root tests.

Kernel-focused tests:

cd src && go test ./internal/kernel/...

The v1-compatible in-repository plugin import remains:

import plugin "rpc_plugin_system/pkg/plugin"

That import path is the local Go module path used by this source release. It is meant for packages built inside this repository checkout; it is not a fetchable external module path and should not be used with go get as a published SDK dependency. The separate v2 SDK source uses module git.dannyhunn.com/agents/plugin-system/sdk/v2; its stable version is not yet published. Do not infer release availability from a source module declaration.

Provider-owned diagnostics should use the structured SDK helper:

err := logger.ProviderDiagnostic(plugin.ProviderDiagnostic{
    CapabilityID:  "mail.send",
    OperationID:   "send_message",
    CorrelationID: "corr-123",
    Status:        plugin.ProviderStatusDegraded,
    ErrorClass:    "upstream_unavailable",
})

The helper routes through the shared provider event validation/redaction contract and returns validation errors instead of writing unsafe events.

Plugin capability strings are small routing/status vocabulary emitted by the SDK/runtime code:

• heartbeat — required core health check support.
• shutdown — required graceful shutdown support.
• echo — optional echo RPC support.
• sleep — optional sleep RPC support used by timeout/failure tests.
• crash — optional crash RPC support used by supervision/failure tests.

TemplatePlugin reports the required core capabilities (heartbeat, shutdown) through SDK detection. Plugins that implement optional interfaces add echo, sleep, and/or crash; plugins may also provide an explicit Capabilities() []string override for test and compatibility scenarios.

Local enrollment operator candidate: configuration and one-time handoff.