Skip to Content

Plugins

What a plugin is, where conciv finds plugins, and the test-runner plugin as a worked example.

A plugin adds tools, skills and RPC methods to the engine, and panels, slots and pills to the widget. It has up to three parts:

  • The engine part runs inside the conciv engine. It adds tools the agent calls, skills it reads, and RPC methods. See Engine SDK.
  • The RPC contract names the methods and events both parts share.
  • The browser part runs in the widget. It adds panels, slots, composer pills and settings pages. See Browser SDK.

You can call any plugin's RPC methods from a terminal with conciv plugin call. See Calling a plugin from the terminal.

Add a plugin from your config

List plugins in the plugins option of conciv(). An entry is a name, or [name, options]:

vite.config.ts
conciv({plugins: [['@conciv/plugin-test-runner', {runner: 'playwright'}]]})
  • A package name loads the installed package.
  • A path that starts with ./ or ../ resolves from the project folder. A file:// URL works too. A path must point to a folder, not a file.
  • Every option value must be JSON: a string, number, boolean, null, array or object. The plugin reads them as ctx.options.

Add a plugin in the project

conciv also loads every plugin in a conciv/plugins (or conciv/plugin) folder at the project root. Each .ts or .js file there is a plugin, and so is each folder. No config entry is needed.

index.ts
rpc.ts

The engine watches these folders and the configured plugin paths, and reloads a plugin when its files change.

Where conciv looks inside a plugin

PartIn a packageIn a folder
Engine partthe ./server export, else the main exporta server file, else an index file
RPC contractthe ./rpc exportan rpc file
Browser partthe ./plugin-experimental export (a .cjs)plugin-experimental.cjs or .js

A file in a folder can be .ts, .tsx, .js, .jsx, .mts, .mjs, .cts or .cjs. A folder whose package.json has a name and exports is read like a package.

The test-runner package exports all three:

packages/plugins/test-runner/package.json
"exports": {
  ".": {"types": "./dist/index.d.ts", "import": "./dist/index.js"},
  "./server": {"types": "./dist/index.d.ts", "import": "./dist/index.js"},
  "./rpc": {"types": "./dist/rpc.d.ts", "import": "./dist/rpc.js"},
  "./plugin-experimental": "./dist/plugin-experimental.cjs"
}

Worked example: the test runner

@conciv/plugin-test-runner powers live tests. Every part of it uses the public SDK.

Options. The engine part parses ctx.options with zod. runner defaults to vitest.

src/index.ts
const testRunnerConfig = z.object({
  runner: z.enum(['vitest', 'jest', 'node-test', 'playwright']).default('vitest'),
})

Setup. Plugin.define names the plugin and runs it when the engine loads it. It adds the tools, a skill and the RPC handlers. The test runner is written on the promise entry. For the Effect form, see Define the plugin.

Tools. test_runner_run and test_runner_status are direct tools the agent calls by name. list stays in code mode as external_test_runner_list. See Tools.

RPC. The contract in src/rpc.ts declares status, current, list, ui, run and stop, and one event event. The Tests tab calls these methods and follows the events. See RPC.

Browser part. src/plugin-experimental.tsx adds the Tests tab as a panel.

Next

On this page