paperclip-plugins/plugin-agent-permissions/README.md

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

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

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

You should see plugin-agent-permissions in the list.

Uninstall

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

License

MIT

Author

FrenoCorp