@meetopenbot/plugin-sdk 0.1.2 → 0.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +37 -41
- package/dist/helpers.d.ts.map +1 -1
- package/dist/ui.d.ts +2 -1
- package/dist/ui.d.ts.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# OpenBot Plugin SDK
|
|
2
2
|
|
|
3
|
-
The official SDK for building plugins for [OpenBot](https://meetopenbot.com). This SDK provides the types and helpers needed to create plugins that
|
|
3
|
+
The official SDK for building plugins for [OpenBot](https://meetopenbot.com). This SDK provides the types and helpers needed to create plugins that act as **agent runtimes**—handling events, interacting with storage, and rendering UI widgets within the OpenBot ecosystem.
|
|
4
4
|
|
|
5
5
|
## Installation
|
|
6
6
|
|
|
@@ -8,28 +8,30 @@ The official SDK for building plugins for [OpenBot](https://meetopenbot.com). Th
|
|
|
8
8
|
npm install @meetopenbot/plugin-sdk
|
|
9
9
|
```
|
|
10
10
|
|
|
11
|
+
OpenBot plugins **must** be **ESM** (ECMAScript modules): `import` / `export` in the plugin entry, with a package configured as a module (for example `"type": "module"` in `package.json`, or an `.mjs` entry). CommonJS (`require`) is not supported.
|
|
12
|
+
|
|
11
13
|
## How it Works
|
|
12
14
|
|
|
13
|
-
OpenBot plugins operate on an event-driven architecture powered by [Melony](https://github.com/meetopenbot/melony).
|
|
15
|
+
OpenBot plugins operate as the **agent runtime** on an event-driven architecture powered by [Melony](https://github.com/meetopenbot/melony).
|
|
14
16
|
|
|
15
17
|
1. **Registration**: The host loads your plugin and calls the `factory` function with a `PluginContext`.
|
|
16
|
-
2. **Subscription**: Your `factory` function uses the `PluginBuilder` to subscribe to
|
|
17
|
-
3. **Processing**: When
|
|
18
|
-
4. **
|
|
18
|
+
2. **Subscription**: Your `factory` function uses the `PluginBuilder` to subscribe to the full event surface (e.g., `agent:invoke`).
|
|
19
|
+
3. **Processing**: When a user sends a message, `agent:invoke` is dispatched. Your plugin runs its loop, performs logic, interacts with `storage`, or calls external APIs.
|
|
20
|
+
4. **Communication**: Your plugin emits events back to the bus (e.g., `agent:output` or `client:ui:widget`) to communicate with the user or the parent agent.
|
|
19
21
|
|
|
20
22
|
## Core Concepts
|
|
21
23
|
|
|
22
24
|
### Plugin
|
|
23
25
|
|
|
24
|
-
A plugin is defined by the `Plugin` or `PluginModule` interface. Use `definePlugin` to get full OpenBot typing
|
|
26
|
+
A plugin is defined by the `Plugin` or `PluginModule` interface. Use `definePlugin` to get full OpenBot typing.
|
|
25
27
|
|
|
26
28
|
```typescript
|
|
27
29
|
import { definePlugin } from '@meetopenbot/plugin-sdk';
|
|
28
30
|
|
|
29
31
|
export default definePlugin({
|
|
30
|
-
id: 'my-
|
|
31
|
-
name: 'My
|
|
32
|
-
description: 'A
|
|
32
|
+
id: 'my-agent',
|
|
33
|
+
name: 'My Agent',
|
|
34
|
+
description: 'A custom AI agent',
|
|
33
35
|
configSchema: {
|
|
34
36
|
type: 'object',
|
|
35
37
|
properties: {
|
|
@@ -37,66 +39,61 @@ export default definePlugin({
|
|
|
37
39
|
},
|
|
38
40
|
required: ['apiKey'],
|
|
39
41
|
},
|
|
40
|
-
toolDefinitions: {
|
|
41
|
-
get_weather: {
|
|
42
|
-
description: 'Get the current weather',
|
|
43
|
-
inputSchema: {
|
|
44
|
-
type: 'object',
|
|
45
|
-
properties: {
|
|
46
|
-
location: { type: 'string' },
|
|
47
|
-
},
|
|
48
|
-
},
|
|
49
|
-
},
|
|
50
|
-
},
|
|
51
42
|
factory: (context) => (builder) => {
|
|
52
43
|
builder.on('agent:invoke', async function* (event) {
|
|
53
|
-
// Handle
|
|
44
|
+
// Handle agent logic here
|
|
54
45
|
});
|
|
55
46
|
},
|
|
56
47
|
});
|
|
57
48
|
```
|
|
58
49
|
|
|
59
|
-
|
|
50
|
+
### Events
|
|
60
51
|
|
|
61
|
-
|
|
52
|
+
Plugins communicate via an event bus. Core events include:
|
|
62
53
|
|
|
63
|
-
|
|
54
|
+
- `agent:invoke`: Dispatched when a user sends a message to the agent.
|
|
55
|
+
- `agent:output`: Emitted by the plugin to send messages back to the user or feedback final results to a parent agent.
|
|
56
|
+
- `client:ui:widget`: Used to render interactive UI widgets (forms, choices, etc.) in the client.
|
|
57
|
+
- `client:ui:widget:response`: Dispatched when a user interacts with a widget (e.g., submits a form or clicks a choice).
|
|
58
|
+
- `action:<toolName>`: Dispatched when a tool call is requested.
|
|
59
|
+
- `action:<toolName>:result`: Emitted when a tool handler finishes. Must include `data.output: string` to be fed back to the model.
|
|
64
60
|
|
|
65
|
-
|
|
66
|
-
- **`toolDefinitions`**: Defines the tools your plugin provides. Other plugins (like a runtime plugin) can use these definitions to call your plugin's tools.
|
|
61
|
+
### Output and Communication
|
|
67
62
|
|
|
68
|
-
|
|
63
|
+
OpenBot is oriented toward **complete messages**. Use the `agentOutput` helper to emit full step text or final results.
|
|
69
64
|
|
|
70
|
-
|
|
65
|
+
- **Multiple Outputs**: A single plugin can emit multiple `agent:output` events during a single turn to show progress.
|
|
66
|
+
- **Parent Communication**: The **latest `agentOutput`** is the primary way to communicate with a parent agent and provide the final results of the agent's execution.
|
|
71
67
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
-
|
|
68
|
+
### Implementation Strategies
|
|
69
|
+
|
|
70
|
+
OpenBot plugins are designed for **AI agent behavior**, not just thin translation layers. You can implement this behavior in two primary ways:
|
|
71
|
+
|
|
72
|
+
1. **Third-Party Agent Harness**: If your target platform provides a full agent stack (built-in tools, context management, and reasoning), you can wrap it directly. Examples include **Claude Code**, **Codex**, or other "full agent" SDKs. You connect their internal lifecycle to OpenBot via this SDK's events.
|
|
73
|
+
2. **Custom Agentic Logic**: If the third-party provider only offers a regular API, SDK, or CLI without agentic intelligence, it is recommended to use the [**Vercel AI SDK**](https://sdk.vercel.ai/docs) to build the agent loop. This allows you to add the necessary "intelligence" and tool-calling capabilities on top of the raw integration.
|
|
77
74
|
|
|
78
75
|
### Storage
|
|
79
76
|
|
|
80
|
-
The `PluginContext` provides access to the `storage` interface
|
|
77
|
+
The `PluginContext` provides access to the `storage` interface for interacting with:
|
|
81
78
|
|
|
82
79
|
- **Channels & Threads**: Manage conversation contexts.
|
|
83
|
-
- **Agents**: Access and update agent details.
|
|
84
80
|
- **Variables**: Store configuration or secrets.
|
|
85
|
-
- **Files**: Read and list files in the
|
|
81
|
+
- **Files**: Read and list files in the workspace.
|
|
86
82
|
- **Memories**: Store and retrieve long-term memory records.
|
|
87
83
|
|
|
88
84
|
### UI Widgets
|
|
89
85
|
|
|
90
|
-
Plugins can render interactive UI widgets using the `uiWidget` helper
|
|
86
|
+
Plugins can render interactive UI widgets using the `uiWidget` helper and handle user interactions by subscribing to `client:ui:widget:response`:
|
|
91
87
|
|
|
92
88
|
- `message`: Simple text message with optional actions.
|
|
93
89
|
- `choice`: A set of buttons for the user to choose from.
|
|
94
|
-
- `form`: A form with various field types
|
|
90
|
+
- `form`: A form with various field types.
|
|
95
91
|
- `list`: A list of items with status indicators.
|
|
92
|
+
- `media`: Images, video, audio, or files.
|
|
96
93
|
|
|
97
|
-
## Example: Hello World
|
|
94
|
+
## Example: Hello World Agent
|
|
98
95
|
|
|
99
|
-
This
|
|
96
|
+
This agent responds to any message with "Hello, World!".
|
|
100
97
|
|
|
101
98
|
```typescript
|
|
102
99
|
import { definePlugin, shouldHandleInvoke, agentOutput } from '@meetopenbot/plugin-sdk';
|
|
@@ -122,7 +119,6 @@ export default definePlugin({
|
|
|
122
119
|
## API Reference
|
|
123
120
|
|
|
124
121
|
- [Plugin & Context](./src/plugin.ts)
|
|
125
|
-
- [Runtime Types](./src/runtime.ts)
|
|
126
122
|
- [Events & State](./src/events.ts)
|
|
127
123
|
- [Storage Interface](./src/storage.ts)
|
|
128
124
|
- [UI Widget Specs](./src/ui.ts)
|
package/dist/helpers.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,gBAAgB,EAChB,SAAS,EACT,eAAe,EACf,aAAa,EACd,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,kBAAkB,
|
|
1
|
+
{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../src/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,gBAAgB,EAChB,SAAS,EACT,eAAe,EACf,aAAa,EACd,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,kBAAkB,EAAG,MAAM,SAAS,CAAC;AAEnD,yEAAyE;AACzE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAGpF;AAED,qCAAqC;AACrC,wBAAgB,WAAW,CAAC,IAAI,EAAE;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB,GAAG,gBAAgB,CAUnB;AAED,+EAA+E;AAC/E,wBAAgB,UAAU,CAAC,KAAK,EAC9B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE;IAAE,IAAI,CAAC,EAAE,SAAS,CAAA;CAAE,EAC7B,IAAI,EAAE,KAAK,GACV,eAAe,CAAC,KAAK,CAAC,CAMxB;AAED,wCAAwC;AACxC,wBAAgB,QAAQ,CAAC,IAAI,EAAE;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB,GAAG,aAAa,CAUhB;AAED,oEAAoE;AACpE,wBAAgB,QAAQ,CAAC,CAAC,SAAS;IAAE,IAAI,CAAC,EAAE,SAAS,CAAA;CAAE,EACrD,MAAM,EAAE;IAAE,IAAI,CAAC,EAAE,SAAS,CAAA;CAAE,EAC5B,KAAK,EAAE,CAAC,GACP,CAAC,GAAG;IAAE,IAAI,CAAC,EAAE,SAAS,CAAA;CAAE,CAS1B"}
|
package/dist/ui.d.ts
CHANGED
|
@@ -8,7 +8,7 @@ export type UIWidgetAction = {
|
|
|
8
8
|
export type UIWidgetField = {
|
|
9
9
|
id: string;
|
|
10
10
|
label: string;
|
|
11
|
-
type: 'text' | 'textarea' | 'number' | 'boolean' | 'select' | 'multiselect' | 'date';
|
|
11
|
+
type: 'text' | 'textarea' | 'number' | 'boolean' | 'select' | 'multiselect' | 'date' | 'password';
|
|
12
12
|
description?: string;
|
|
13
13
|
placeholder?: string;
|
|
14
14
|
required?: boolean;
|
|
@@ -51,6 +51,7 @@ export type UIWidgetBase = {
|
|
|
51
51
|
display?: 'expanded' | 'collapsed';
|
|
52
52
|
size?: 'small' | 'medium' | 'large' | 'full';
|
|
53
53
|
metadata?: Record<string, unknown>;
|
|
54
|
+
variant: "default" | "basic";
|
|
54
55
|
};
|
|
55
56
|
export type UIMessageWidget = UIWidgetBase & {
|
|
56
57
|
kind: 'message';
|
package/dist/ui.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,cAAc,GAAG;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,SAAS,GAAG,WAAW,GAAG,QAAQ,CAAC;IAC7C,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,aAAa,GAAG,MAAM,CAAC;
|
|
1
|
+
{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"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"}
|