Plugin Development

Build runtime plugins with manifests, tools, task context, admin state, and UI surfaces.

Plugins extend Noema without adding plugin-specific branches to core runtime code. They should expose capabilities through generic hooks.

Plugin Layout

plugins/example-plugin/
  plugin.json
  index.mjs
  src/
    tools.mjs

Manifest

plugin.json describes the plugin and points to its entry file:

{
  "name": "example-plugin",
  "version": "0.1.0",
  "description": "Adds example runtime tools.",
  "entry": "./index.mjs"
}

Use stable names because settings, logs, and admin surfaces may refer to the manifest name.

Entry Module

An entry module should export the hooks the plugin supports. Keep hook behavior explicit and avoid hidden global side effects.

export default {
  registerTools(registry) {
    registry.register({
      name: "example.echo",
      description: "Return the provided text.",
      inputSchema: {
        type: "object",
        properties: {
          text: { type: "string" }
        },
        required: ["text"]
      },
      async execute(input) {
        return { text: input.text };
      }
    });
  }
};

Hook Responsibilities

Hook	Use For	Avoid
`registerTools`	External actions, filesystem, browser, shell, integrations	Dialogue-only behavior
`extendPrompt`	Short, bounded model instructions	Large dynamic context dumps
`resolveTaskContext`	Evidence needed before task execution	Long-lived UI state
`transformText`	Clear text normalization steps	Hidden policy changes
`selectExpression`	Visual or voice expression state	Runtime execution decisions
`getAdminState`	Plugin settings and diagnostics	Secret exposure
`handleAdminAction`	Plugin configuration actions	Arbitrary command execution
`uiSurfaces`	Plugin-owned interface panels	Core desktop layout changes

Tool Design

Good tools are narrow, inspectable, and easy to verify.

Use precise names such as browser.open_page or files.apply_patch.
Validate inputs before doing work.
Return structured results with enough evidence for the task runtime.
Make destructive actions explicit.
Avoid embedding provider credentials in tool responses.

Verification

For changed runtime plugin .mjs files:

node --check plugins/example-plugin/index.mjs
node --check plugins/example-plugin/src/tools.mjs

When plugin changes affect SDK or desktop runtime contracts, also run:

pnpm --filter @noema/sdk build
pnpm --filter @noema/desktop build