docs: add 11 new documentation files across all categories
New reference docs: - agents/ref-btmsg.md: inter-agent messaging schema and CLI - agents/ref-bttask.md: kanban task board operations - providers/ref-providers.md: Claude/Codex/Ollama/Aider comparison - config/ref-settings.md: (already committed) New guides: - contributing/dual-repo-workflow.md: community vs commercial repos - plugins/guide-developing.md: Web Worker sandbox API and publishing New pro docs: - pro/features/knowledge-base.md: persistent memory + symbol graph - pro/features/git-integration.md: context injection + branch policy - pro/marketplace/README.md: 13 plugins catalog Split files: - architecture/data-model.md: from architecture.md (schemas, layout) - production/hardening.md: from production.md (supervisor, sandbox, WAL) - production/features.md: from production.md (FTS5, plugins, secrets, audit)
This commit is contained in:
Hibryda
parent
8251321dac
commit
b6c1d4b6af
11 changed files with 2198 additions and 0 deletions
173
docs/pro/marketplace/README.md
Normal file
173
docs/pro/marketplace/README.md
Normal file
|
|
@ -0,0 +1,173 @@
|
|||
# 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;
|
||||
}
|
||||
```
|
||||
Loading…
Add table
Add a link
Reference in a new issue