Plugin System
Relevant source files
The following files were used as context for generating this wiki page:
The Orcy Plugin System is a bundled, manifest-declared extension architecture designed to provide safe, local-first extensibility to the task orchestration platform. Plugins allow developers to contribute new capabilities through typed extension points such as notification channels, signal detectors, and lifecycle interceptors. They are loaded at server boot from a local filesystem directory and must adhere to a strict manifest contract to execute.
Plugins are categorized by their operational scope: System Plugins shape server-wide infrastructure (e.g., notification channels), while Habitat Plugins produce per-habitat content or behavior and must be explicitly enrolled by a habitat administrator. This dual-scope model ensures that infrastructure remains stable while allowing for customized automation and monitoring within individual workspaces.
Sources: CONTEXT.md:275-296, README.md:95-99
Core Architecture and Lifecycle
The plugin system operates on a manifest-based contract where each plugin must declare its identity, version, and contributions. The system follows a "safe-load" pattern where plugins are validated against a capability whitelist and security constraints before being integrated into the application runtime.
Plugin Loading and Validation
During the server boot sequence, the PluginManager scans the designated PLUGINS_DIR for .mjs modules. Each module is expected to export a manifest that Orcy uses to register contributions.
The validation phase ensures that plugin IDs match their filenames and that contribution kinds (e.g., notificationChannel, signalDetector, lifecycleInterceptor) are valid.
Sources: CONTEXT.md:275-283, packages/api/src/test/plugins.test.ts:43-78
Extension Points and Contributions
Orcy supports several types of plugin contributions, summarized in the table below:
| Contribution Kind | Scope | Description |
|---|---|---|
notificationChannel | System | Registers a delivery route for attention requests (e.g., Slack, Discord, Webhooks). |
signalDetector | Habitat | Automated pattern matching over pulses, task events, or comments to emit detected signals. |
lifecycleInterceptor | Habitat | Pre-veto or post-emit logic that intercepts task and mission state changes. |
customMcpTool | System | Defines dynamic tools accessible via the Model Context Protocol (MCP). |
Sources: CONTEXT.md:280-302, packages/api/src/test/plugins.test.ts:133-145
Plugin Enrollment and Execution
While System Plugins are enabled via the PLUGINS_ENABLED environment variable at boot, Habitat Plugins require a per-habitat enrollment process.
Enrollment Mechanism
Enrollment is a configuration row that opts a specific habitat into a plugin's functionality. This process includes:
- Capability Approval: Habitat admins must approve the capabilities a plugin requests (e.g.,
taskWriter). - Configuration: A habitat-specific config blob is validated against the plugin's schema.
- Audit Trail: Every enrollment action is logged for traceability.
Sources: CONTEXT.md:297-302, packages/api/src/test/pluginTaskPublication.test.ts:114-122
Task Creation via Plugins
Plugins with the taskWriter capability can programmatically create tasks. This process is governed by Orcy's kernel to ensure integrity, routing through a "reserve-prepare-govern-publish" chain.
Tasks created by plugins carry distinct metadata, including a creationIntegrity version of POST_CUTOVER and a causal root identifying the specific plugin_run that triggered the action.
Sources: packages/api/src/test/pluginTaskPublication.test.ts:13-33, packages/api/src/test/pluginTaskPublication.test.ts:182-198
Security and Constraints
The system enforces strict boundaries to prevent unauthorized actions and resource exhaustion.
Security Guardrails
- Capability Whitelisting: Plugins are restricted from accessing certain payloads or writing pulses unless they explicitly declare and are granted the required capabilities (e.g.,
pulseReader,pulseWriter). - Write Caps: To prevent "infinite loops" or resource spam, the system enforces a
ORCY_PLUGIN_WRITE_CAP. If a plugin exceeds this allotment during a single run, subsequent write requests are denied. - Quarantine Logic: Plugins that exhibit faulty behavior or repeatedly fail are moved into a quarantine state, disabling their contributions until addressed.
- SSRF Protection: Outbound requests from plugins (such as webhook deliveries) are filtered through the
ORCY_SSRF_ALLOWLIST.
Sources: packages/api/src/test/plugins.test.ts:98-115, packages/api/src/test/pluginTaskPublication.test.ts:128-135, README.md:288-292
Idempotency and Replays
For operations like task creation, the system uses a combination of runId and actionKey. If a plugin attempts to execute the same action within the same run context, the system replays the previous result rather than creating duplicate entities.
Sources: packages/api/src/test/pluginTaskPublication.test.ts:204-225, packages/mcp/src/api.ts:153-157
Summary
The Orcy Plugin System provides a robust framework for extending the platform's orchestration capabilities while maintaining strict security and isolation. By separating infrastructure-level System Plugins from behavior-level Habitat Plugins and enforcing a manifest-based contract, Orcy ensures that automated signals, notifications, and task lifecycle interceptions are predictable, auditable, and safe.