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

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

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

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

```bash
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

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

## License

MIT

## Author

FrenoCorp