@coro-ai/plugin-sdk

Public SDK for authoring [Coro](https://github.com/coro-ai) plugins.

A Coro plugin teaches the runner how to talk to a specific source-control provider (GitHub, BitBucket, GitLab, …) or issue tracker (Jira, Linear, GitHub Issues, …). The runner is provider-agnostic — every per-provider detail lives in a plugin.

Quick start

coro plugin init my-provider
cd ~/.coro/plugins/my-provider
npm install
$EDITOR index.ts        # implement cloneInfo / matchesRemote / pollPr / normalizeInbound
coro start              # restart the runner; the plugin is detected via coro-plugin.json

The CLI scaffolds a directory with:

coro-plugin.json — manifest read by the runner’s drop-in loader.
package.json — pre-wired with @coro-ai/plugin-sdk as a dependency.
index.ts — a stub implementing the four required hooks.
intelligence/ — markdown the runner copies into the per-job intelligence overlay.

What you implement

Plugins ship under one of three contracts:

Contract	Use when	Required hooks
`ScmPluginBase`	Source-control providers (PRs, branches, repo creation)	`init`, `cloneInfo`, `matchesRemote`, `pollPr`
`TrackerPluginBase`	Issue trackers (tickets, transitions, links)	`init` (+ either `mcpServer` OR all of `getIssue`/`commentIssue`/`transitionIssue`)
`ExecutorPluginBase`	LLM phase execution engines (e.g. Anthropic, OpenAI)	`init`, `createRuntime` returning a `PhaseExecutor` (`executePhase`, `capabilities`, optional `normalizeInbound`)

All three bases inherit:

manifest: PluginManifest — id, version, configSchema, webhook descriptor, intelligence contributions.
Optional mcpServer() — when present, the runner attaches the upstream MCP server to every job session, exposing mcp__<pluginId>__* tools to the agent. This is the MCP-first pivot’s primary outbound channel; most modern providers ship an MCP server you can point at.
Optional normalizeInbound(req) — collapse provider webhook payloads into a NormalizedEvent so the runner can resume parked jobs.
Optional intelligenceRoot() — points at a folder of markdown the resolver copies into the per-job intelligence overlay (clone-URL recipes, transition-name cheatsheets, …).

Helpers

The SDK ships small utilities so plugin code stays focused on the integration:

verifyHmacSignature({ algorithm, secret, rawBody, signatureHeader }) — HMAC-verify a webhook body against the provider’s signature header (handles sha256=<hex> / sha1=<hex> / raw-hex shapes).
mcpStdioDescriptor({ command, args, env }) — build a stdio MCP server descriptor with sensible defaults.
buildExternalRef({ kind, pluginId, externalId, repoKey, url }) — construct a provider-neutral pointer for PRs / tickets / repos / issues. Validates that kind: 'pull_request' carries a repoKey.
readHeader(headers, name) — case-insensitive header lookup that unwraps string[] shapes.

Trust model

Drop-in plugins execute in the runner’s process. There is no sandbox. Treat installation the same way you would treat installing any other npm dependency on a server: review the source, pin the version, prefer audited / curated registry entries.

The dashboard’s “Available plugins” panel surfaces a small registry of maintainer-reviewed packages; arbitrary npm specs require an explicit confirmation before install.

Running the conformance pack

The runner publishes a re-runnable conformance suite that checks manifest invariants, lifecycle, webhook normalisation, and (for SCM plugins) pollPr/matchesRemote consistency.

// tests/conformance.test.ts in your plugin repo
import { runConformance } from '@coro-ai/runner/tests/plugins/conformance'
import { createMyPlugin } from '../src'

runConformance({
  id: '@vendor/coro-plugin-myprovider',
  factory: () => createMyPlugin(),
  validConfig: { /* valid config */ },
  invalidConfig: { /* missing required fields */ },
})

Stability

The plugin-API host version is 1.0.0. Plugin manifests declare hostCompatibility: '^1.0.0'; the runner refuses plugins whose range does not satisfy its host version. Breaking changes bump the host version’s major segment.