Integrations
How Numinance reaches external systems through plugins that implement typed ports, and which providers, kits and trust mechanisms exist today.
The plugin protocol, the Go plugin SDK, one sample provider, four official providers and the conformance kits are in the public tree and build today. The plugin host that launches providers, the registry and the governed install are part of the proprietary runtime and are not generally available.
Numinance does not reach into GitHub, a CI system, a knowledge base or a ticket tracker with built-in code. It reaches them through providers. A provider is a separate executable that implements a port: a versioned gRPC service in proto/numinance/ports/ with a small set of verbs, each carrying governance annotations (risk class, execution mode, idempotency, dry run, declared evidence). The host launches the provider, reads its manifest, and dispatches one approved action at a time.
This section documents that model end to end: how a plugin is launched and talks to the host, what its manifest declares, how to write one in Go, which providers ship in the public tree, how MCP-backed knowledge fits, how distribution and trust are designed, and how conformance is proven.
The model in one picture
Plugin invocation sequence
In what order do host and provider talk, and who decides what?
Policy allows the action; the provider runs it and every privileged step goes through the host.
Host: Plugin host + policy decision point · Provider: Plugin subprocess · Egress: Broker / egress proxy · Evidence: Evidence writer (runner identity)
Host launches the subprocess
exec + NUMINANCE_PLUGIN_COOKIE
- Message and fields
- NUMINANCE_PLUGIN_COOKIE = MagicCookie (plugin.CookieEnv)
- NUMINANCE_PLUGIN_PROTOCOLS (offer)
- host address env (plugin.HostAddrEnv)
- Who holds authority
- Host: it starts the process and offers the protocol versions. The host identifies the plugin by the connection it established at launch, never by request content.
- ✕ The provider can not
- The cookie is not a secret and not authority: it only stops a user from running the provider binary by hand. A provider with a wrong cookie refuses to serve.
Allowed. Step 1 of 14: Host launches the subprocess. exec + NUMINANCE_PLUGIN_COOKIE. Host: it starts the process and offers the protocol versions. The host identifies the plugin by the connection it established at launch, never by request content.
Text description
Illustrative and simulated: nothing here talks to a running host. RPC and field names are the ones in proto/numinance/plugin/v1 and sdk/go/plugin.
- The host starts the provider subprocess with
NUMINANCE_PLUGIN_COOKIEset to the magic cookie, then callsHandshake,GetManifestandGetDescriptorsonPluginService. - The policy decision and the grant happen on the host, outside the model and before the provider sees the action.
- If allowed, the host calls
Invoke(server-streaming) with anEnvelopewhoseActionContextthe host sets. The provider may call back onHostService:RequestCredentialreturns an opaque handle that only works through the egress proxy, which injects the real token;EmitEvidencesubmits evidence that the host appends under the runner identity;ReportProgressreports progress. - The stream ends with an
ActionResult; the host records the outcome, may callHealth, and finallyShutdown, which first revokes handles and egress grants. - If policy denies,
Invokeis never sent and the denial is recorded as evidence. If the provider requests a credential intent that is not in its declaredcredential_intents, the host rejects it and records the call.
The provider never holds authority: it cannot approve, widen a grant, see a credential, or append evidence.
The diagram is interactive. It walks one invocation through the host, the provider process, the egress proxy and the evidence writer, with an allowed, a denied and an undeclared-action scenario. The plugin lifecycle page explains each step against the protocol files.
Provider families and ports
Each port is one family of providers. A port is a contract, not an implementation: any system that has the concepts the port names can implement every core verb, and a vendor feature beyond the core is a capability negotiated at handshake, never an escape hatch.
| Port package | Verbs (core) | Provider in the public tree | Conformance kit |
|---|---|---|---|
numinance.ports.scm.v1 | GetRepository, GetTree, GetFile, ListBranches, CreateBranch, GetBranchProtection, OpenPullRequest, UpdatePullRequest, CommentOnPullRequest, GetPullRequestStatus, MergePullRequest, SearchCode | plugins/official/scm-github (all twelve core verbs registered; no VendorCall) | conformance/scm/v1 (runnable, CORE-001 to CORE-010) |
numinance.ports.ciexecutor.v1 | StartOperation, GetOperation, CancelOperation, ListArtifacts, GetLogReference | plugins/official/ci-github-actions | conformance/ciexecutor/v1 (runnable, CORE-001 to CORE-008) |
numinance.ports.verifier.v1 | Run | plugins/official/verifier-python, plugins/official/verifier-repo | conformance/verifier/v1 (runnable subset) |
numinance.ports.knowledge.v1 | Search, Fetch, Resolve | plugins/examples/sample-knowledge (a sample, not a connector) | conformance/knowledge/v1 (runnable subset) |
numinance.ports.ticketing.v1 | GetIssue, SearchIssues, CommentOnIssue, TransitionIssue, LinkIssue | none in the tree | conformance/ticketing/v1 (replay kit, proven against an in-memory fake) |
numinance.ports.authorexecutor.v1 | Capabilities, Execute, Plan | none in plugins/; stream rules in sdk/go/ports/authorexecutor | conformance/authorexecutor/v1 (case list only) |
numinance.ports.sandboxprovider.v1 | Create, Exec, Wait, Snapshot, Destroy | none | conformance/sandboxprovider/v1 (case list only) |
numinance.ports.evidencestore.v1 | AppendLocked, GetRecord, ListRange, Head | none | conformance/evidencestore/v1 (case list only) |
numinance.ports.transparencylog.v1 | Append, Checkpoint, Prove, Lookup | none | conformance/transparencylog/v1 (case list only) |
Two things stand out. First, the ticketing port is part of the public contract and has a kit, but no provider for any tracker is in the tree; the kit is proven against a small in-memory fake and a provider's own test is expected to call it. Second, the ports that sit on the trust boundary (sandbox provider, evidence store, transparency log) are bound to a deployment, not installed from a registry: the sandbox provider kit states that a registry-installed sandbox provider is refused.
Presence is not readiness
A directory under plugins/ is a statement that the code builds against the public SDK, not that it is ready for production. Every official provider README lists work that is not done, and the SBOM and provenance references in the manifests are placeholders that governed install would refuse. See Official providers.
How ports relate to kinds
Two vocabularies meet here and they are easy to confuse.
| Port | Kind | |
|---|---|---|
| What it is | A gRPC service a plugin implements | A YAML document a person writes (apiVersion: numinance.dev/v1) |
| Where it lives | proto/numinance/ports/*/v1/*.proto | proto/numinance/kinds/v1/*.proto, schemas/examples/ |
| Who consumes it | The host, at dispatch time | numi validate --files and the engine's loader |
| Example link between them | numinance.ports.knowledge.v1 | KnowledgeConnection.spec.provider names the extension id of a knowledge provider that must resolve to a lockfile entry |
A kind configures which provider to use and within what bounds (for example a KnowledgeConnection with read_only: true, a scope, pinned tools and budgets). A port defines what the provider can be asked to do. Neither grants authority: grants are evaluated by policy outside the model.
Extension classes
The manifest field kind is an ExtensionClass, and it bounds what an extension can ever be.
| Class | What it is | Authority |
|---|---|---|
EXTENSION_CLASS_SKILL | Knowledge rendered into guidance | None |
EXTENSION_CLASS_PLAYBOOK | A declarative procedure | Shapes grants, never widens them |
EXTENSION_CLASS_CONTROL_PACK | Checks and constraints | Can only restrict |
EXTENSION_CLASS_CAPABILITY_PROVIDER | An executable plugin implementing ports | Declared intents, enforced by the host |
Only a capability provider may declare ports and capabilities, and therefore intents. This page and the rest of the section are about capability providers.
Invariants that hold for every provider
- Policy decides before the provider runs. The host dispatches
Invokeonly after a policy decision and a grant check, and the provider cannot change theActionContextthe host built. Your policy decides. Not the model. - Ports are never model tools. The port files state that no verb is exposed to a model and that only named contexts call them, under named identities.
- The plugin describes; the host authorises and enforces. A manifest is a declaration to be compared against grants, not a permission.
- No credential material crosses the boundary. A provider asks for a handle and sends it to the egress proxy, which applies the credential.
- Evidence is appended by the host. A provider submits evidence items; it never appends to the chain.
- Everything a provider returns is a claim. Responses are bounded, strictly decoded and checked; unknown fields and over-limit values are rejected, never repaired.
Where each topic lives
Plugin lifecycle
Launch, magic cookie, handshake, manifest, descriptors, Invoke stream, host callbacks, health and shutdown, with failure semantics.
Manifest and capabilities
What a plugin declares: side effects, credential, network and filesystem intents, digest, provenance and permission changes.
Write a plugin in Go
The sample knowledge provider, line by line, with the build result and the conformance kit it runs against.
Official providers
GitHub source control, GitHub Actions, and two verifiers: what each does, what is tested, what is not done.
Knowledge through MCP
The read-only knowledge port, the KnowledgeConnection kind, and the designed MCP bridge.
Registry and trust
Designed distribution: signed, digest-pinned, permission-declared extensions, and approved capability-gap synthesis.
Conformance
Every kit under conformance/, its modes, how to run it and what a pass does not mean.
Validation and errors
What the open numi validate checks, what it deliberately leaves to the engine, the exit codes, and the real error messages you will see.
Plugin lifecycle
The full life of a provider process, from the host launching it to shutdown, with the exact RPCs, bounds and failure behavior of plugin/v1.