Plugin SDK
Dependencies & contracts
Independent plugins, optional capabilities and versioned public schemas.
Use optional integrations when two plugins can enrich each other but remain independently useful. Public schemas belong to the provider plugin and ship with it. The SDK contains only neutral references, compatibility and authorization mechanisms.
The implemented Tasks ↔ Calendar example
Tasks Calendar
task-summary@1.0.0 ◄── attach-task ────────── event.taskRef
schedule/display ───► event-record@1.0.0 + event-summary@1.0.0
Generic SDK: eligibility + live reference requirements
Generic host: current rights + versioned atomic writesBoth manifests have dependencies: []. Reciprocal optional integrations are evaluated after selecting enabled installations, so they do not create a required dependency cycle.
| Consumer feature | Required provider contracts |
|---|---|
meinkontext.calendar.attach-task | Tasks >=0.0.1 <0.1.0; meinkontext.tasks.task-summary@1.0.0. |
meinkontext.tasks.attach-event | Calendar >=0.0.1 <0.1.0; both meinkontext.calendar.event-summary@1.0.0 and meinkontext.calendar.event-record@1.0.0. |
Tasks queries Calendar's published taskRef.objectId record field to discover events, then resolves the summary for display. This is why a summary contract alone is insufficient. Removing the record contract disables that Tasks feature even if Calendar itself still works.
Provider responsibilities
- Own the canonical format and strict schema in your package.
- Publish stable contract IDs/versions, schema IDs and packaged JSON paths in
publicContracts. - Include the corresponding JSON Schemas in
PluginDefinition.schemas. - Implement
publicProjectionwith exact version handling and schema validation of its output. The host checks current access and contract availability and supplies the trusted reference; the provider must parse its returned projection. - Keep previous contracts compatible or introduce a new version. Never silently change a field's meaning under the old version.
Publication is a schema promise, not public access to records. Do not copy a provider's private implementation schema into the SDK.
Consumer declaration
The actual Calendar declaration has this shape:
optionalIntegrations: [{
id: "meinkontext.calendar.tasks-integration",
requires: [{
pluginId: "meinkontext.tasks",
version: ">=0.0.1 <0.1.0",
contracts: [{ id: "meinkontext.tasks.task-summary", version: "1.0.0" }],
}],
features: ["meinkontext.calendar.attach-task"],
}]host.integrationFeatures(consumerPluginId) intersects catalog compatibility with enabled installations. Use it to decide which controls to render and which workflow to offer. It is eligibility, not permission to read any particular record.
Do not import the other plugin's runtime or reach into its private record fields. Consume the published contract. Define a required dependency only if the base plugin cannot function without it; required cycles are rejected.
Enforce on the command, not just the button
A hidden UI control cannot protect direct MCP calls or retries. Declare action-specific requirements in DomainRuntime.requirements:
requirements(actionId, input) {
const command = commandSchema.parse(input);
if (command.taskRef) return {
features: ["meinkontext.calendar.attach-task"],
references: [{
ref: command.taskRef,
contractId: "meinkontext.tasks.task-summary",
version: "1.0.0",
}],
};
return { features: [], references: [] };
}This fragment illustrates the requirement result; the real runtime must also validate actionId and distinguish commands with/without reference fields. The host checks features and provider contract access inside the owner transaction, before executing or replaying a cached result. Current implementation requires a live reference in that owner organization. A restricted execution credential cannot gain additional reference reads through this mechanism.
Removing a link should not require the unavailable provider. Independent edits may preserve an opaque stored link; attaching/replacing one requires current provider rights. Define this distinction explicitly in your command schema instead of resubmitting a hidden reference with every form edit.
One canonical connection
Calendar stores taskRef; Tasks does not write a reciprocal event array. A scheduling operation writes one Calendar event. It does not rewrite the task, assign anyone, move its due date, complete it or send an invitation.
Consumers resolve each side under its own rights. A shared calendar may display its own event and opaque reference while the linked private task remains unavailable. Do not fall back to a copied task title after revocation. Counts/reports also must be based on authorized resources.
Degradation matrix
| State | Required behavior |
|---|---|
| Provider absent from build | Consumer base functions work, feature absent; no implementation import that breaks startup. |
| Provider present but disabled | Consumer base functions work; no new links or successful link replay. Stored references persist. |
| Incompatible plugin/contract version | Feature absent; no guessing schema shape. |
| Source access revoked | Resolution and dependent commands fail; no stale private-content fallback. |
| Consumer disabled | Its writes fail; retained authorized reader/export continues. |
| Provider returns later | Re-evaluate compatibility and current access; do not invent new grants or duplicate links. |
Organizational disable and build removal are different: disable does not remove schemas/reader code from the binary. Build removal removes the contribution; preserve the reviewed reader when existing data needs to remain exportable.
Planned collaboration extension
Cross-owner references are a planned next capability, not supported by the current same-owner requirement check. Existing collection sharing across organizations does not remove this restriction. The implementation gate requires separate destination write and source contract/read checks, a reviewed cross-scope revocation/commit/replay model, no private-content fallback, and independent edits/unlinking when access disappears. The host must remain domain-neutral and preserve one canonical consumer-side link.
The collaboration roadmap also requires clear owner/effective-role information in pickers and detail views, a second authorized live-user acceptance, and a reusable absent/disabled/incompatible/re-enabled contract matrix. These are foundational usability and SDK release criteria; arbitrary new plugin combinations are not declared validated by the current Tasks/Calendar evidence.
Verification checklist
Prove each plugin independently, then both together. Verify the entire source record and revision remain unchanged when creating a link. Test repeat requests, stale revisions, incompatible contracts, disabled companions, unlinking while disabled, private source access, revocation between calls and replay after revocation. Exercise both plugin directions and the real OAuth/MCP surface. A real Calendar-only server/web build additionally guards against accidental implementation imports.
See TESTING.md. This design does not supply generic cross-plugin transactions, arbitrary UI slot injection, event buses or schedules. The implemented Messages pilot is described below; broader autonomous workflows remain separate.
Messages composition
Messages owns conversation-summary and conversation-record; Tasks and Calendar declare optional discuss features requiring both contracts. Messages separately declares optional Task/Event summary contracts for live context links. All three have an empty required-dependency list. A due date still works without Calendar; a task and an event still work without Messages.
Messages never assigns a Task, accepts an invitation, books an Event or changes source bytes. A reference grants no access. Source titles are resolved only under current same-owner rights; an unavailable provider/access renders an unavailable link. Removing an old link remains possible without the provider. Disabled/missing/incompatible providers hide the corresponding entry points and reject new links, including stale-command replays. Cross-owner typed references remain a separate roadmap gate; plain shared conversations can cross account/organization boundaries.
Private format upgrades and mandatory policy reads
Tasks workflow v2 demonstrates a provider-owned format upgrade: Task/Project v1 remain readable, new writes use v2, and task-summary@1.0.0 remains unchanged for Calendar/Messages. Consumers do not import private workflow fields or acquire a required dependency. Unknown versions fail explicitly; no opportunistic lossy conversion.
Graceful optional behavior never applies to authorization prerequisites. A plugin whose command depends on collection policy records declares readScope.requiredFormats and the host capability documents.required-formats. The host requires all matching records to be readable at admission and replay; a hidden or newly revoked policy causes UNAVAILABLE, not a permissive default. A host without this capability cannot admit that plugin release. The host treats format IDs generically.