Plugin development

This guide is for Open Nua Plugin authors. It explains how to turn domain capability into an installable, inspectable, and governable workbench: choose a runtime, declare permissions, organize the package, test locally, and publish through the Hub.

A Plugin is a versioned delivery unit. The package may contain Skills, domain logic, UI declarations, runtime adapters, and data contracts. Gateway mediates approved tools, while Desktop loads only capability that is enabled. This keeps domain teams productive without creating a second identity, policy, or deployment boundary.

Two authoring paths

Third-party or business teams

The author owns the Plugin package, Skill instructions, runtime implementation, tests, and release material. A remote runtime must be deployed and approved by the target organization. The manifest cannot point at an arbitrary upstream URL.

Open Nua maintained Plugins

The Open Nua team may also maintain official packages and their domain services under the shared Plugin runtime. The same manifest, authorization, review, and release rules apply; official ownership does not make the capability implicitly trusted.

The shortest useful loop is:

choose a runtime → write PLUGIN.md → declare manifest and Skills
→ load locally → test in a conversation → package → publish to Hub

Plugin and Skill boundaries

Keep the Skill focused on how to do the work. Keep permissions, runtime endpoints, and package metadata in the manifest and runtime contract.

Package layout

my-plugin/
├── .open-nua/
│   └── manifest.json
├── PLUGIN.md
├── skills/
│   └── research.md
├── runtime/
│   ├── src/
│   └── tests/
├── ui/
│   └── declarations/
└── README.md

The exact directories can vary by runtime, but every package needs a stable manifest and a human-readable authoring contract. Do not include secrets, local state, or generated credentials in the package.

Manifest essentials

The manifest should make the capability reviewable before installation. At minimum, describe:

• package name, display name, owner, and version;
• supported runtime and entry point;
• permissions and data sources;
• configuration keys and whether they are required;
• tools or operations exposed to an Agent;
• artifacts produced by a run;
• actions that require human confirmation;
• compatibility and migration notes.

Use internal implementation names only in source-level identifiers. User-facing names, labels, and release notes use the Open Nua brand.

Runtime and Gateway

The runtime should be deterministic about inputs, outputs, errors, and cancellation. Gateway is the policy-controlled entry point for approved tools and shared services. A Plugin must not bypass it with a hidden network call or a direct credential lookup.

Every call should carry enough context to audit the decision: thread, workspace, user or organization identity, authorization scope, and Plugin version. If required context cannot be verified, fail closed and return an actionable error.

Skills that work well

Write Skills as small, composable instructions:

1. State when the Skill applies and when it must not run.
2. Name the required context, files, tools, and permissions.
3. Define the expected output and artifact locations.
4. Explain confirmation points and unsafe operations.
5. Include a short verification checklist.

Avoid pretending that a Skill is a general system prompt. It should describe one repeatable unit of domain work and leave product policy to the platform.

Local development

Validate the manifest and package before opening Desktop. Start the runtime with local-only configuration, load the package into a test workspace, and exercise both successful and denied calls. Test cancellation, missing context, malformed input, retries, and partial output.

The acceptance bar is a user-visible path:

install → inspect permissions → enable → start a thread
→ run a capability → confirm when needed → inspect artifacts

Publishing and operations

Publish a reproducible archive to the Hub with a release note, checksum, compatibility range, and rollback guidance. The Hub validates the package; the organization decides whether to enable it. Keep runtime rollout and package rollout separately observable.

For an official package, also document its owner, support path, data handling, and deprecation plan. For a third-party package, make the deployment and approval boundary explicit.

Security checklist

• No secrets or personal tokens in source, manifests, or examples.
• Least-privilege permissions with a reason for each permission.
• Network access goes through an approved Gateway path.
• Destructive or externally visible actions pause for confirmation.
• Logs and artifacts avoid sensitive payloads unless explicitly required.
• Package and runtime versions are recorded for every execution.
• Failure is fail-closed when authorization or context is missing.

Release checklist

• Manifest is valid and version is bumped intentionally.
• PLUGIN.md and Skills describe the current behavior.
• Local success, denial, cancellation, and retry paths pass.
• Generated artifacts are deterministic and inspectable.
• Package contains no credentials or local state.
• Hub metadata, release notes, checksum, and rollback are ready.
• Organization enablement and runtime deployment owners are identified.

When these checks pass, the Plugin is ready to be reviewed as a governed capability—not merely uploaded as a bundle of code.