209 lines
4.7 KiB
Markdown
209 lines
4.7 KiB
Markdown
# @paperclipai/plugin-agent-permissions
|
|
|
|
Per-agent permission toggling for fine-grained access control in Paperclip.
|
|
|
|
## Overview
|
|
|
|
This plugin provides a UI for managing per-agent permissions, allowing administrators to enable or disable specific capabilities for each agent in their organization.
|
|
|
|
### Permission Keys
|
|
|
|
- `agents:create` - Create new agents
|
|
- `users:invite` - Invite new users to the company
|
|
- `users:manage_permissions` - Manage user permissions
|
|
- `tasks:assign` - Assign tasks to agents
|
|
- `tasks:assign_scope` - Control task assignment scope
|
|
- `joins:approve` - Approve join requests
|
|
|
|
## Installation
|
|
|
|
### Local Development
|
|
|
|
```bash
|
|
# Clone or navigate to the plugin directory
|
|
cd plugin-agent-permissions
|
|
|
|
# Install dependencies
|
|
pnpm install
|
|
|
|
# Build the plugin
|
|
pnpm build
|
|
```
|
|
|
|
### Development Mode
|
|
|
|
```bash
|
|
# Watch mode - rebuilds on changes
|
|
pnpm dev
|
|
|
|
# UI dev server with hot-reload (optional)
|
|
pnpm dev:ui
|
|
```
|
|
|
|
### Testing
|
|
|
|
```bash
|
|
# Run tests
|
|
pnpm test
|
|
|
|
# Type checking
|
|
pnpm typecheck
|
|
```
|
|
|
|
## Plugin Structure
|
|
|
|
```
|
|
plugin-agent-permissions/
|
|
├── src/
|
|
│ ├── manifest.ts # Plugin metadata and capabilities
|
|
│ ├── worker.ts # Worker entry point with handlers
|
|
│ └── ui/
|
|
│ ├── index.tsx # UI entry point
|
|
│ ├── AgentPermissionsTab.tsx # Detail tab component
|
|
│ └── PermissionsNav.tsx # Sidebar navigation
|
|
├── tests/
|
|
│ └── worker.test.ts # Unit tests
|
|
├── esbuild.config.mjs # Build configuration
|
|
├── tsconfig.json # TypeScript config
|
|
├── vitest.config.ts # Test configuration
|
|
└── package.json # Dependencies and scripts
|
|
```
|
|
|
|
## Worker Handlers
|
|
|
|
### Data Handlers
|
|
|
|
#### `agent-permissions`
|
|
Returns permissions for a single agent.
|
|
|
|
```typescript
|
|
// Input: { agentId: string }
|
|
// Output: { agentId: string, permissions: Record<PermissionKey, boolean> }
|
|
```
|
|
|
|
#### `all-agents-permissions`
|
|
Returns all agents with their permissions.
|
|
|
|
```typescript
|
|
// Input: { companyId?: string }
|
|
// Output: Array<{ agentId: string, agentName: string, permissions: Record<PermissionKey, boolean> }>
|
|
```
|
|
|
|
### Actions
|
|
|
|
#### `toggle-agent-permission`
|
|
Enables or disables a permission for an agent.
|
|
|
|
```typescript
|
|
// Input: { agentId: string, permissionKey: PermissionKey, enabled: boolean }
|
|
// Output: { success: true }
|
|
```
|
|
|
|
## UI Entrypoints
|
|
|
|
### Detail Tab (`permissions`)
|
|
|
|
Shown on agent detail pages. Displays all permissions with toggle controls.
|
|
|
|
### Sidebar Navigation (`permissions-nav`)
|
|
|
|
Global navigation entry for accessing the permissions management interface.
|
|
|
|
## Publishing to npm
|
|
|
|
### Prerequisites
|
|
|
|
1. An npm account with publish permissions
|
|
2. The `@paperclipai/plugin-sdk` must be published to npm (currently in development)
|
|
|
|
### Steps
|
|
|
|
1. **Update package.json**
|
|
```json
|
|
{
|
|
"private": false,
|
|
"version": "1.0.0",
|
|
"publishConfig": {
|
|
"access": "public"
|
|
}
|
|
}
|
|
```
|
|
|
|
2. **Replace local SDK references**
|
|
|
|
Change from:
|
|
```json
|
|
"@paperclipai/plugin-sdk": "file:.paperclip-sdk/paperclipai-plugin-sdk-1.0.0.tgz"
|
|
```
|
|
|
|
To:
|
|
```json
|
|
"@paperclipai/plugin-sdk": "^1.0.0"
|
|
```
|
|
|
|
3. **Build and publish**
|
|
```bash
|
|
pnpm build
|
|
npm publish
|
|
```
|
|
|
|
### For Local Development Only
|
|
|
|
The current setup uses `.paperclip-sdk/` tarballs for local development against an unpublished SDK:
|
|
|
|
```bash
|
|
# The scaffolded package.json already points to local SDK files
|
|
"@paperclipai/plugin-sdk": "file:.paperclip-sdk/paperclipai-plugin-sdk-1.0.0.tgz"
|
|
```
|
|
|
|
This allows development before the SDK is officially published to npm.
|
|
|
|
## Install Into Paperclip (Local Development)
|
|
|
|
### Step 1: Build the plugin
|
|
|
|
```bash
|
|
cd plugin-agent-permissions
|
|
pnpm install
|
|
pnpm build
|
|
```
|
|
|
|
### Step 2: Install into Paperclip
|
|
|
|
After building, install the plugin into your local Paperclip instance using the API:
|
|
|
|
```bash
|
|
curl -X POST http://localhost:3100/api/plugins/install \
|
|
-H "Content-Type: application/json" \
|
|
-H "Authorization: Bearer <your-api-key>" \
|
|
-d '{"packageName":"/home/mike/code/paperclip_plugins/plugin-agent-permissions","isLocalPath":true}'
|
|
```
|
|
|
|
**Note:** Replace `<your-api-key>` with your Paperclip API key. For local development, you can get this from browser dev tools or the CLI config.
|
|
|
|
The server watches local-path plugins and will automatically restart the worker after rebuilds.
|
|
|
|
### Step 3: Verify installation
|
|
|
|
```bash
|
|
curl http://localhost:3100/api/plugins \
|
|
-H "Authorization: Bearer <your-api-key>"
|
|
```
|
|
|
|
You should see `plugin-agent-permissions` in the list.
|
|
|
|
## Uninstall
|
|
|
|
```bash
|
|
curl -X DELETE http://localhost:3100/api/plugins/paperclipai.plugin-agent-permissions \
|
|
-H "Authorization: Bearer <your-api-key>"
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|
|
|
|
## Author
|
|
|
|
FrenoCorp
|