Skip to main content

Go API

:::note Release-candidate phase The Go binding go.dagstack.dev/plugin-system ships as v0.1.0-rc.1 (Phase 1 surface — in-process only). Promotion to a v0.1.0 stable tag follows after a soak period and a docs-examples sweep across all three bindings. :::

Surface available today​

The shape of the API is fixed by ADR-0001. Key types in the Go binding:

package pluginsystem

// Plugin — anything that implements the Plugin interface.
type Plugin interface {
    Setup(ctx PluginContext) error
    Teardown() error
}

// Registry — holds loaded plugins, manages their lifecycle.
type Registry interface {
    Plugins() []*RegisteredPlugin
    Get(kind, name string) (Plugin, error)
    SetupAll() error
    TeardownAll() error
}

// Discovery — entry point.
func Discover(path string, opts ...DiscoverOption) (Registry, error)

What the reference will cover​

  • Public symbols from go.dagstack.dev/plugin-system.
  • Plugin-kind interfaces (LLM, VectorStore, Chunker, Tool, ...).
  • Dispatchers (BroadcastCollectDispatcher, ChainDispatcher, CapabilityDispatcher).
  • Standard resources (Clock, Rng, BlobStore, HTTPClient) plus their test doubles.
  • MCP adapters for out-of-process plugins (Phase 2 scope).

The reference is generated by godoc with markdown output and committed to site/docs/api/go/.

Phase 1 caveats​

  • Out-of-process runtimes (mcp_stdio, mcp_http) are explicitly rejected with ErrRuntimeNotSupported — they land in Phase 2.
  • The core_version constraint check is currently non-empty validation only; full semver / PEP-440 specifier matching arrives in Phase 2.

Alternatives if you cannot wait for the stable tag​

  • Treat plugins as external services through MCP HTTP. A Python-backed plugin runs as a separate HTTP service and the Go application calls it via the standard MCP client — once Phase 2 ships.
  • Use gRPC/REST bridges with a custom serialisation of manifests — not recommended, the entire contract is lost.