new plugin

plugin-agent-inbox-config/README.md

@@ -0,0 +1,106 @@
+# @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.