# Plugin Marketplace

> This documentation covers Pro edition features available in the agents-orchestrator/agents-orchestrator private repository.

## Overview

The Plugin Marketplace provides a curated catalog of plugins for Agents Orchestrator. It handles discovery, installation, updates, and removal of plugins from a central GitHub-hosted repository. The community plugin runtime (Web Worker sandbox, permission model) is unchanged -- the marketplace adds distribution and lifecycle management on top.

## Catalog

The plugin catalog is a JSON file hosted in the `agents-orchestrator/agor-plugins` GitHub repository:

```
https://raw.githubusercontent.com/agents-orchestrator/agor-plugins/main/catalog.json
```

### Catalog Schema

```typescript
interface PluginCatalog {
  version: number;             // Catalog schema version
  updatedAt: string;           // ISO 8601 timestamp
  plugins: CatalogEntry[];
}

interface CatalogEntry {
  id: string;                  // Unique plugin identifier
  name: string;                // Display name
  description: string;         // Short description
  version: string;             // Semver version
  author: string;              // Author name
  tier: 'free' | 'paid';      // Availability tier
  downloadUrl: string;         // HTTPS URL to plugin archive (.tar.gz)
  checksum: string;            // SHA-256 hex digest of the archive
  size: number;                // Archive size in bytes
  permissions: string[];       // Required permissions
  minVersion: string;          // Minimum Agents Orchestrator version
  tags: string[];              // Categorization tags
}
```

## Plugin Catalog

### Free Plugins (8)

| ID | Name | Description |
|----|------|-------------|
| `session-stats` | Session Stats | Displays token count, cost, and turn count as a compact overlay |
| `git-log-viewer` | Git Log Viewer | Shows recent git history for the active project in a formatted panel |
| `task-export` | Task Exporter | Exports bttask board contents to markdown or JSON |
| `prompt-library` | Prompt Library | User-managed collection of reusable prompt templates |
| `session-notes` | Session Notes | Per-session scratchpad persisted as tasks-KV entries |
| `time-tracker` | Time Tracker | Records wall-clock time per agent session with daily summaries |
| `diff-viewer` | Diff Viewer | Renders unified diffs from agent tool calls with syntax highlighting |
| `agent-logger` | Agent Logger | Streams agent messages to a local JSONL file for offline analysis |

### Paid Plugins (5)

| ID | Name | Description |
|----|------|-------------|
| `cost-alerts` | Cost Alerts | Configurable cost threshold notifications with Slack/webhook delivery |
| `team-dashboard` | Team Dashboard | Aggregated usage analytics across multiple workstations |
| `policy-engine` | Policy Engine | Custom rules for agent behavior (blocked commands, file restrictions) |
| `audit-export` | Audit Exporter | Exports audit logs to external SIEM systems (JSON, CEF formats) |
| `model-benchmark` | Model Benchmark | A/B testing framework for comparing model performance on identical tasks |

## Install Flow

1. User opens the Marketplace tab in the settings panel.
2. The UI fetches `catalog.json` from GitHub (cached for 1 hour).
3. User selects a plugin and clicks Install.
4. The backend downloads the plugin archive from `downloadUrl` over HTTPS.
5. The backend verifies the SHA-256 checksum against `checksum` in the catalog entry.
6. On checksum match, the archive is extracted to `~/.config/bterminal/plugins/{plugin-id}/`.
7. The plugin's `plugin.json` manifest is validated (required fields, permission declarations).
8. The plugin appears in the installed list and can be activated.

## Uninstall Flow

1. User selects an installed plugin and clicks Uninstall.
2. The backend calls `unloadPlugin()` if the plugin is currently active.
3. The plugin directory `~/.config/bterminal/plugins/{plugin-id}/` is deleted.
4. Any tasks-KV entries prefixed with `plugin:{plugin-id}:` are purged.

## Update Flow

1. On marketplace tab open, the UI compares installed plugin versions against catalog versions.
2. Plugins with available updates show an Update button.
3. Update performs: download new archive, verify checksum, unload plugin, replace directory contents, reload plugin.
4. The plugin's state (tasks-KV entries) is preserved across updates.

## Security

### Checksum Verification

Every plugin archive is verified against its SHA-256 checksum before extraction. If the checksum does not match, the install is aborted and an error is shown. This prevents tampered archives from being installed.

### HTTPS-Only Downloads

Plugin archives are only downloaded over HTTPS. The `downloadUrl` field is validated to start with `https://`. HTTP URLs are rejected.

### Path Traversal Protection

During archive extraction, all file paths are validated to ensure they resolve within the target plugin directory. Paths containing `..` segments or absolute paths are rejected. This prevents a malicious archive from writing files outside the plugin directory.

### Sandbox Isolation

Installed plugins run in the same Web Worker sandbox as community plugins. The marketplace does not grant additional privileges. Each plugin's permissions are declared in `plugin.json` and enforced by the plugin host at runtime.

## Commands

### pro_marketplace_fetch_catalog

Fetches the plugin catalog from GitHub. Returns cached data if fetched within the last hour.

**Response:** `PluginCatalog`

### pro_marketplace_install

Downloads, verifies, and installs a plugin.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `pluginId` | `String` | Yes | Plugin identifier from catalog |

### pro_marketplace_uninstall

Removes an installed plugin and its files.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `pluginId` | `String` | Yes | Plugin identifier |

### pro_marketplace_update

Updates an installed plugin to the latest catalog version.

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `pluginId` | `String` | Yes | Plugin identifier |

### pro_marketplace_list_installed

Returns all installed plugins with their versions and active state.

**Response:** `Vec<InstalledPlugin>`

```typescript
interface InstalledPlugin {
  id: string;
  name: string;
  version: string;
  installedAt: string;
  isActive: boolean;
  hasUpdate: boolean;
  latestVersion: string | null;
}
```

### pro_marketplace_check_updates

Compares installed plugins against the catalog and returns available updates.

**Response:** `Vec<PluginUpdate>`

```typescript
interface PluginUpdate {
  id: string;
  currentVersion: string;
  latestVersion: string;
  changelogUrl: string | null;
}
```
