agent-orchestrator/docs/pro/marketplace

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

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>

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>

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