# @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.