paperclip-plugins/plugin-agent-permissions

@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

# Clone or navigate to the plugin directory
cd plugin-agent-permissions

# Install dependencies
pnpm install

# Build the plugin
pnpm build

Development Mode

# Watch mode - rebuilds on changes
pnpm dev

# UI dev server with hot-reload (optional)
pnpm dev:ui

Testing

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

// Input: { agentId: string }
// Output: { agentId: string, permissions: Record<PermissionKey, boolean> }

all-agents-permissions

Returns all agents with their permissions.

// 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.

// 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

   {
     "private": false,
     "version": "1.0.0",
     "publishConfig": {
       "access": "public"
     }
   }
   

2. Replace local SDK references

   Change from:

   "@paperclipai/plugin-sdk": "file:.paperclip-sdk/paperclipai-plugin-sdk-1.0.0.tgz"
   

   To:

   "@paperclipai/plugin-sdk": "^1.0.0"
   

3. Build and publish

   pnpm build
   npm publish
   

For Local Development Only

The current setup uses .paperclip-sdk/ tarballs for local development against an unpublished SDK:

# 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)

The API port may vary depending on your setup. Common ports are 3100 (dev server) or 8087. Check your Paperclip startup logs or use curl http://localhost:3100/api/health to find the correct port.

Step 1: Build the plugin

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:

curl -X POST http://localhost:3100/api/plugins/install \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -d '{"packageName":"/absolute/path/to/paperclip_plugins/plugin-agent-permissions","isLocalPath":true}'

Note:

• Replace <your-api-key> with your Paperclip API key
• Replace /absolute/path/to/paperclip_plugins with the actual absolute path to this repository
• The port (3100) may need to be changed to match your Paperclip instance (e.g., 8087)

The server watches local-path plugins and will automatically restart the worker after rebuilds.

Step 3: Verify installation

curl http://localhost:3100/api/plugins \
  -H "Authorization: Bearer <your-api-key>"

You should see plugin-agent-permissions in the list. (Replace 3100 with your port if different.)

Uninstall

curl -X DELETE http://localhost:3100/api/plugins/paperclipai.plugin-agent-permissions \
  -H "Authorization: Bearer <your-api-key>"

License

MIT

Author

FrenoCorp