107 lines
3.4 KiB
Markdown
107 lines
3.4 KiB
Markdown
# @paperclipai/plugin-agent-inbox-config
|
|
|
|
Plugin for configuring per-agent inbox-lite filter settings via UI.
|
|
|
|
## What It Does
|
|
|
|
This plugin provides a UI for configuring which issues appear in each agent's inbox via the `inbox-lite` endpoint. Instead of using query parameters or code changes, users can use a simple interface with toggles to control:
|
|
|
|
- **Issue statuses** - Which issue statuses (todo, in_progress, blocked, etc.) should appear in the inbox
|
|
- **Project filter** - Optionally limit to issues from a specific project
|
|
- **Goal filter** - Optionally limit to issues linked to a specific goal
|
|
- **Search query** - Optional text search to filter issues by title, description, or comments
|
|
- **Include backlog** - Toggle to include/exclude backlog issues
|
|
|
|
## UI Slots
|
|
|
|
The plugin registers three UI slots:
|
|
|
|
1. **Sidebar entry** (`agent-inbox-config-sidebar`) - Quick access to select an agent and navigate to their inbox config
|
|
2. **Page** (`agent-inbox-config-page`) - Overview page showing all agents with their current inbox configuration summaries
|
|
3. **Agent detail tab** (`agent-inbox-tab`) - Full configuration form on each agent's detail page
|
|
|
|
## Configuration
|
|
|
|
### Instance Config Schema
|
|
|
|
The plugin supports the following instance-level configuration:
|
|
|
|
```json
|
|
{
|
|
"defaultStatuses": "todo,in_progress,blocked",
|
|
"includeBacklog": false,
|
|
"maxIssuesPerAgent": 50
|
|
}
|
|
```
|
|
|
|
- `defaultStatuses`: Comma-separated list of statuses to use as default for new agents
|
|
- `includeBacklog`: Whether to include backlog issues by default
|
|
- `maxIssuesPerAgent`: Maximum number of issues returned per agent inbox (1-500)
|
|
|
|
### Per-Agent Config Storage
|
|
|
|
Each agent's inbox configuration is stored in two places:
|
|
|
|
1. **Plugin state** - Under the key `agentInboxConfigs` scoped to `instance`. This allows the plugin to quickly read/write configs without querying the database.
|
|
|
|
2. **Agent runtimeConfig** - The config is also persisted to the agent's `runtimeConfig.inboxConfig` field for durability and to be available even if the plugin is uninstalled.
|
|
|
|
## Data Handlers
|
|
|
|
The plugin registers the following data handlers for UI components:
|
|
|
|
- `agents` - Lists all agents in a company
|
|
- `getAgentInboxConfig` - Gets the inbox config for a specific agent
|
|
- `listAgentInboxConfigs` - Lists all agent inbox configs
|
|
|
|
## Action Handlers
|
|
|
|
The plugin registers the following action handlers:
|
|
|
|
- `setAgentInboxConfig` - Sets or updates an agent's inbox configuration
|
|
- `resetAgentInboxConfig` - Resets an agent's config to defaults
|
|
|
|
## Events
|
|
|
|
The plugin subscribes to:
|
|
|
|
- `agent.created` - Automatically sets default inbox config for new agents
|
|
|
|
## Capabilities Required
|
|
|
|
```json
|
|
[
|
|
"agents.read",
|
|
"projects.read",
|
|
"goals.read",
|
|
"issues.read",
|
|
"plugin.state.read",
|
|
"plugin.state.write",
|
|
"ui.sidebar.register",
|
|
"ui.page.register"
|
|
]
|
|
```
|
|
|
|
## Local Install (Dev)
|
|
|
|
From the repo root, build the plugin and install it:
|
|
|
|
```bash
|
|
pnpm --filter @paperclipai/plugin-agent-inbox-config build
|
|
pnpm paperclipai plugin install ./packages/plugins/plugin-agent-inbox-config
|
|
```
|
|
|
|
## Usage
|
|
|
|
1. Navigate to an agent's detail page in Paperclip
|
|
2. Click the "Inbox Settings" tab
|
|
3. Configure the filters:
|
|
- Check/uncheck issue statuses
|
|
- Select a project filter (optional)
|
|
- Select a goal filter (optional)
|
|
- Enter a search query (optional)
|
|
- Toggle include backlog
|
|
4. Click "Save Configuration"
|
|
|
|
The agent's inbox-lite endpoint will now return issues matching these filters.
|