> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comet.rpamis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Plugin SDK

> Register capabilities, connect storage and context, and enforce installation, enabled status, and scope.

Plugin SDK manages registration, installation, enabled status, scopes, and capability calls. Use it with Workflow Runtime or independently in your host.

## Define a named capability

This TypeScript example registers a text-length plugin. `MemoryPluginStateStore` keeps installation state only in this process and does not access user configuration.

```ts theme={null}
import {
  PluginRuntime,
  MemoryPluginStateStore,
  definePlugin,
  definePluginCapability,
  createPluginClient,
} from '@rpamis/comet/plugins';

const plugin = definePlugin({
  id: 'example.notes',
  kind: 'third-party',
  version: '1',
  scopes: ['user'],
  compatible: (version) => version === '0.5.0',
  create: () => ({
    capabilities: {
      length: definePluginCapability({
        parseInput(value: unknown) {
          if (typeof value !== 'string') throw new Error('Expected text');
          return value;
        },
        invoke: (text) => text.length,
      }),
    },
  }),
});

const plugins = new PluginRuntime({
  cometVersion: '0.5.0',
  store: new MemoryPluginStateStore(),
  descriptors: [plugin],
});

// Run after host installation permission; this example keeps state in memory.
await plugins.install(plugin.id, 'user');
const client = createPluginClient(plugins, plugin);
const length: number = await client.invoke('length', 'hello');
console.log(length);
```

Registration is not installation or enablement. Named clients infer capability names, inputs, and outputs and propagate errors, while enabled status and scope constraints remain effective.

Save as `plugin.ts` in a project with the SDK installed and run npx tsx plugin.ts. The output is 5, from the installed length capability. This example does not call a model or store knowledge.

`parseInput`'s return shape is also the client input contract. If you need to extract text from an object, do so in invoke, keeping public types consistent with accepted input.

## Query, disable, and enable

Append this code:

```ts theme={null}
console.log(await plugins.get(plugin.id));
await plugins.disable(plugin.id);
try {
  await client.invoke('length', 'hello');
} catch (error) {
  console.log(String(error));
}
await plugins.enable(plugin.id);
console.log(await client.invoke('length', 'hello'));
```

The disabled call is rejected; after enablement the output is 5 again. install, enable, disable, and uninstall manage installation and availability separately. Removing a UI button does not disable a plugin.

This example uses an in-memory State Store, so a new process requires installation again. Persist installation status with `JsonPluginStateStore` and its file read/write and locking interfaces. Installation state and business storage are different responsibilities; this example has no business data.

## Call a plugin from a workflow

Call client.invoke inside a [host handler](/en/sdk/executors.md) and return its value as the actual Outcome. Workflow declares a tool step; Plugin Runtime enforces installation, enabled status, and current scope. Handle actual failure or unknown-result paths when calls throw, without returning invented success values.

## Context and experience events

Plugins may provide context candidates, on-demand expansion, and experience-event subscriptions. The host decides when to query, how to supply context, and when to record behavior and results.

Type inference neither establishes implementation trust nor supplies a sandbox. Validate business input/output separately; external effects need actual permission and reconciliation.

## Connect Comet plugins

`@rpamis/comet/plugins/comet` exports CometPluginBridge and createDefaultCometPluginBridge to assemble personal memory, project knowledge, and host plugins.

See [personal memory](/en/plugins/personal-memory.md) and [project knowledge](/en/plugins/project-rules.md). Capability calls do not grant workflow approval or advance Native or Classic automatically.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.