Skip to main content

doc_id: fusion-plugins-ecosystem/readme product: fusion-plugins-ecosystem class: platform entry: developer doc_type: readme title: {zh: "Fusion-Plugins-Ecosystem", en: "Fusion-Plugins-Ecosystem"} audience: developer status: draft version: 0.8.0 updated: 2026-11-07 owner: "@dahai" source_of_truth:

  • README.md

🔌 Fusion-Plugins-Ecosystem

Plugin registry, lifecycle manager, and native Claude full-chain adaptation layer for fusion-cowork.

Build on fusion-cowork. Expose every plugin to Claude. Zero adapter code.

English | 简体中文

macOS Python fusion-cowork Claude MCP Tests Version Coverage License


Fusion-Plugins-Ecosystem

Plugin registry, lifecycle manager, and native Claude full-chain adaptation layer built on fusion-cowork. Every plugin auto-exposes as a Claude Skill and an MCP Tool. Zero per-plugin adapter code.

简体中文版见 README_CN.md。

📋 Overview

fusion-plugins-ecosystem is the upper-layer submodule of fusion-cowork. It is not a standalone project — process hosting, permission control, log collection, and resource throttling are all provided by fusion-cowork. This package only adds:

  1. Plugin registry — declarative manifests, param schemas, capability declarations
  2. Lifecycle manager — load/unload/enable/disable/hot-reload, timeout meltdown, auto-restart, INLINE/PROCESS sandbox modes
  3. Claude full-chain adaptation — plugins auto-convert to Claude Code Skills, Agents, Plugin Bundles; expose as MCP Tools (2026-07-28)
  4. Token metering — split Claude model consumption vs plugin local compute, JSON persistence
  5. MCP protocol stack — stdio/SSE/HTTP transports, JSON-RPC 2.0 handler, MCP Server CLI
  6. Plugin sandbox — process isolation via subprocess IPC, resource limits, heartbeat monitoring
  7. Cowork context bridge — reuse fusion-cowork's MCP gateway, hardware scheduler, session pool

Architecture

fusion-plugin-ecosystem        ← this package: registry, lifecycle, Claude adaptation, sandbox, MCP server
        ↓ depends on API
fusion-cowork runtime          ← base runtime: MCP gateway, hardware, sessions, logging
        ↓
fusion-mlx core                ← Mac local inference kernel (Metal/MLX)

Claude three-layer compatibility

Access Constant Gateway entry
Claude Desktop client CLAUDE_DESKTOP list_mcp_tools + gateway_info (stdio transport)
VS Code Claude Code plugin CLAUDE_CODE dispatch_subagent + list_subagent_capable_plugins
Web Claude CLAUDE_WEB invoke_mcp_tool (HTTP/SSE relay)
Volcengine Claude Coding Plan CLAUDE_VOLCENGINE store_credentials("volcengine_claude", ...)

Bidirectional:

  • Forward: Claude calls all fusion local capabilities (image/video generation, MLX local inference, file ops, quantization tools)
  • Reverse: fusion-cowork proactively spins up Claude Code subagents for batch refactors, PR generation, code optimization

See docs/claude-compatibility.md for the full spec.

🚀 Quick Start

Installation

PyPI (recommended; MCP server + console, no cowork runtime):

pip install fusion-plugins-ecosystem
# console UI extra (FastAPI + uvicorn)
pip install "fusion-plugins-ecosystem[console]"

fusion-plugin-server --transport stdio   # MCP server for Claude Desktop / Claude Code
fusion-plugin-console --port 8795        # Extensions console web UI

Homebrew (macOS, Apple Silicon):

brew install dahai80/fusion-mlx/fusion-plugins-ecosystem

From source (full development install; the in-tree fusion-cowork runtime is not on PyPI):

# Clone
git clone https://github.com/dahai80/fusion-plugins-ecosystem.git
cd fusion-plugins-ecosystem

# Create venv (avoid PEP 668)
python3 -m venv .venv
.venv/bin/pip install -e ../fusion-cowork    # base runtime (not on PyPI)
.venv/bin/pip install -e ".[test]"

# Run tests
.venv/bin/python -m pytest --cov=fusion_plugins_ecosystem --cov-report=term-missing -q
# → 747 passed
import fusion_plugins_ecosystem as fpe

# Registry + built-in caveman compressor
registry = fpe.PluginRegistry()
registry.register_builtin()

# Claude full-chain gateway
lifecycle = fpe.PluginLifecycle(registry)
gw = fpe.ClaudeGateway(registry, lifecycle)

# Forward: expose to Claude
skills = gw.export_skills()  # → Claude Skill dicts
tools = gw.list_mcp_tools()  # → MCP tool descriptors

# Forward: Claude calls via MCP
resp = await gw.invoke_mcp_tool("caveman_compress", {"text": "# comment\ncode"})
# → {"content": [{"type":"text","text":"{\"compressed\":\"code\",...}"}], "isError": false}

# Reverse: pull Claude Code subagent
task = fpe.SubagentTask(
    name="compress-session",
    plugin_id="caveman_compress",
    arguments={"text": "a\n\n\n\nb"},
)
result = await gw.dispatch_subagent(task)
# → {"state": "completed", "result": {"compressed": "a\n\nb", ...}}

🧩 Writing a plugin

from fusion_plugins_ecosystem.registry import (
    PluginCapability,
    PluginCategory,
    PluginManifest,
    PluginParam,
)


def my_plugin(desk, params):
    desk.log("my_plugin", "INFO", "called", chars=len(params["text"]))
    return {"echo": params["text"].upper()}


MY_MANIFEST = PluginManifest(
    id="my_echo",
    name="Echo Plugin",
    version="0.1.0",
    category=PluginCategory.CUSTOM,
    description="Echoes input text uppercased.",
    capabilities=[
        PluginCapability.MCP_TOOL,  # auto-expose as MCP Tool
        PluginCapability.CLAUDE_SKILL,  # auto-convert to Claude Skill
    ],
    params=[
        PluginParam(name="text", type="string", description="Input", required=True),
    ],
    entry_point=my_plugin,
    timeout_seconds=60,
)

Register once → it auto-appears in Claude's tool catalog and MCP tools/list. No adapter code. See docs/PLUGIN_DEVELOPMENT.md.

📚 Documentation

Doc Content
docs/architecture.md Layering, module map, data flow (forward/reverse), capability mapping, pain points solved
docs/api-reference.md Full public API reference: PluginRegistry, PluginLifecycle, ClaudeGateway, TokenMeter, DeskRuntime, EcosystemConfig
docs/claude-compatibility.md Three-layer compat, forward/reverse flows, volcengine auth, MLX visual backend, token metering, config toggles
docs/PLUGIN_DEVELOPMENT.md Plugin authoring guide: manifest, capabilities, params schema, async, lazy entry, testing checklist
examples/ 9 runnable plugin samples (echo → file_access): each a manifest + test + README. pytest examples/

🗂️ Project structure

fusion-plugins-ecosystem/
├── pyproject.toml
├── LICENSE                       ← Apache 2.0
├── README.md                     ← this file (English)
├── README_CN.md                  ← 中文版
├── docs/
│   ├── architecture.md
│   ├── api-reference.md
│   ├── claude-compatibility.md
│   └
    PLUGIN_DEVELOPMENT.md
├── fusion_plugins_ecosystem/
│   ├── __init__.py               ← top-level exports + Lazy Import
│   ├── desk_runtime.py           ← fusion-cowork runtime handle wrapper
│   ├── registry.py               ← plugin registry + frozen manifest
│   ├── lifecycle.py              ← load/enable/execute + meltdown + restart + INLINE/PROCESS
│   ├── sandbox.py                ← plugin sandbox (process isolation, IPC)
│   ├── transport.py              ← MCP transport layer (stdio/SSE/HTTP)
│   ├── jsonrpc.py                ← MCP JSON-RPC 2.0 handler
│   ├── server.py                 ← MCP Server entry + CLI
│   ├── schema.py                 ← shared schema (SandboxMode, MCPAnnotations, types)
│   ├── skill_adapter.py          ← plugin → Claude Code Skill bundle
│   ├── agent_adapter.py          ← plugin → Claude Code Agent .md
│   ├── plugin_bundle.py          ← Claude Code Plugin bundle generator
│   ├── claude_adapter.py         ← legacy adapter (backward compat)
│   ├── mcp_exporter.py           ← plugin → MCP Tools
│   ├── claude_gateway.py         ← unified Claude full-chain gateway
│   ├── token_meter.py            ← unified token accounting + WAL append-write persistence
│   ├── metrics.py                ← observability: Prometheus counters/gauges + registry
│   ├── cluster_bridge.py         ← multi-node distributed state bridge (cowork cluster sync + failover)
│   ├── connector.py              ← external MCP connector framework (pack install, MCP client, HIGH_RISK approval gate)
│   ├── connector_packs.py        ← first-party connector packs (Feishu/DingTalk/WeCom/Mail/Calendar/Notion)
│   ├── marketplace.py            ← skill/connector pack marketplace (JSON index, install/uninstall)
│   ├── rest_connector.py         ← declarative REST/webhook connector docs (validation, read/write channels, execution contract)
│   ├── extensions_console.py     ← Extensions console backend (issues #30/#41/#42/#43): Connectors + Plugins·MCP + Skills + Sub-agents tabs, capabilities hub, bundle flows, scope revoke + audit
│   ├── audit_events.py           ← authorization audit event stream → fusion-security JSONL pipeline (issue #43)
│   ├── marketplace_api.py        ← marketplace backend API: listing/detail/permissions, install-state, publish/review queue (issue #74)
│   ├── console_app.py            ← FastAPI console app + `fusion-plugin-console` CLI (port 8795)
│   ├── shell_registry.py         ← fusion-gateway shell module registration + fm- key persistence (#30)
│   ├── logging_setup.py          ← structured JSON logging + correlation_id (P3-6)
│   ├── config.py                 ← one-toggle config panel + observers
│   ├── hook_adapter.py           ← Claude Code Plugin hooks adapter
│   └── builtin/
│       ├── __init__.py
│       └── caveman_compress.py        ← built-in token compressor
├── web/
│   ├── extensions.html            ← console GUI (Connectors + Plugins·MCP + Skills + Sub-agents tabs, hub search + market groups)
│   ├── app.css                    ← fs-* design tokens (verbatim)
│   └── shell.js                   ← sidebar injector (brand "Fusion Plugins")
├── examples/                      ← 9 runnable plugin samples (ex01_echo … ex09_file_access)
│   ├── README.md                  ← scenario index + run instructions
│   ├── ex01_echo/                 ← minimal sync plugin
│   ├── ex02_async/                ← async entry point
│   ├── ex03_skill_export/         ← Skill bundle export
│   ├── ex04_subagent/             ← reverse subagent dispatch
│   ├── ex05_mlx_chat/             ← local MLX inference
│   ├── ex06_vram/                 ← VRAM consumer (INLINE)
│   ├── ex07_long_task/            ← timeout meltdown + restart
│   ├── ex08_process_sandbox/      ← PROCESS sandbox isolation
│   └── ex09_file_access/          ← file permission gating
└── tests/                        ← 747 tests
    ├── test_caveman.py
    ├── test_claude_adapter.py
    ├── test_claude_gateway.py
    ├── test_config.py
    ├── test_desk_runtime.py
    ├── test_lifecycle.py
    ├── test_mcp_exporter.py
    ├── test_registry.py
    ├── test_registry_full.py
    ├── test_token_meter.py
    ├── test_jsonrpc.py
    ├── test_jsonrpc_plugins.py
    ├── test_transport_server.py
    ├── test_sandbox.py
    ├── test_hook_adapter.py
    ├── test_phase3_adapters.py
    ├── test_phase4_meter_config.py
    ├── test_schema.py
    ├── test_product_audit.py        ← production audit P0-P3 fix regressions
    ├── test_metrics.py              ← observability metrics + /metrics endpoint
    ├── test_load.py                 ← load/concurrency safety (lifecycle semaphore, metrics thread-safety, sandbox spawn storm, token-meter pressure)
    ├── test_cluster_bridge.py       ← multi-node distributed state (cross-node plugin/vRAM visibility, failover evict, lifecycle sync, cluster-disabled no-op)
    ├── test_connector.py            ← connector framework: pack validation, registry bridge, HIGH_RISK approval gate, persistence, stdio/http MCP client round-trips
    ├── test_connector_packs.py      ← first-party packs structural validation + Feishu acceptance shape + lifecycle load
    ├── test_marketplace.py          ← marketplace: builtin catalog, JSON index load/override, install/uninstall, HTTPS-only constraint
    ├── test_rest_connector.py       ← declarative connector docs: validation, read/write channel split, persistence, execution contract vs local HTTP server
    ├── test_extensions_console.py   ← console backend: connector install/enable/harness, vault (Desk + local Fernet fallback), MCP intake probe/register/tick/call, plugin tick/remove/install, resync, spine derivation
    ├── test_console_app.py          ← FastAPI console: endpoint contract vs GUI, connector/MCP/plugin full flows, static serving
    ├── test_hub.py                  ← capabilities hub (issue #41): builtin bootstrap, four-tab classification, cross-type search, market groups, /api/hub endpoint
    ├── test_install_flow.py         ← bundle install/OAuth/update/uninstall flows (issue #42): per-item states, scope grants, per-use policy, reverse lookup
    ├── test_audit_flow.py           ← authorization audit events → security JSONL pipeline (issue #43): trace-id linkage, scope revoke re-bridge, used-by, HTTP endpoints
    ├── test_registry_contract.py    ← stable registry read contract registry/1.0 (issue #44): kinds/install state, connector auth single-source (pending/granted/revoked), detail, HTTP endpoints
    ├── test_soak.py                 ← long-run stability (token-meter cap, log buffer cap, session LRU cap, counter monotonic no-drift, lifecycle sustained execute no-residual)
    └── test_integration.py

🔌 Connector framework (issue #27)

External MCP connector framework: fusion acts as an MCP client consuming arbitrary external MCP servers, with first-party domestic connector packs and a skill/connector marketplace.

import fusion_plugins_ecosystem as fpe
from fusion_plugins_ecosystem.connector_packs import get_builtin_pack

desk = fpe.DeskRuntime()
registry = fpe.PluginRegistry(desk)
creg = fpe.ConnectorRegistry(
    desk=desk, registry=registry, persist_path="~/.fusion-ecosystem/connectors.json"
)
lifecycle = fpe.PluginLifecycle(registry)

# 1. Install a first-party pack (Feishu / DingTalk / WeCom / Mail / Calendar / Notion)
creg.install_pack(get_builtin_pack("feishu"))

# 2. Tools are bridged into the plugin registry → exposed as MCP tools / cowork nodes
#    e.g. plugin id "connector__feishu__im.message.send"

# 3. HIGH_RISK tools need explicit approval before execution
creg.approve_tool("feishu", "im.message.send")

# 4. Execute via lifecycle (routed through the external MCP server)
resp = await lifecycle.execute(
    "connector__feishu__im.message.send", {"chat_id": "oc_xxx", "content": "hello"}
)

Marketplace — distribute connector packs and cowork markdown skill packages:

from fusion_plugins_ecosystem.marketplace import Marketplace

market = Marketplace(
    creg, marketplace_index="https://my-company/marketplace/index.json"
)  # private index
entries, warnings = (
    market.load_index()
)  # builtin catalog + remote index (index overrides builtin on id collision)
market.install("feishu")  # builtin pack: install directly
market.install("demo_skill")  # skill_package: git/local source → local install dir
market.list_installed()

Key properties:

  • Declarative packs — a pack is pure data (transport/command/url + credential providers + tool specs with risk levels); the external MCP server command defaults are overridable
  • Credentials stay local — providers resolved from DeskRuntime.get_api_key (Fernet-encrypted) at connect time; stdio → env vars, HTTP → Authorization header
  • Approval gating — HIGH risk tools raise PermissionError until approve_tool(); all read-only tools are LOW risk by convention (enforced by tests)
  • INLINE-only — connector tools run INLINE (the external MCP server is already an isolated process); sandbox_default_mode=process blocks installation
  • First-party packs: Feishu (official lark-mcp), DingTalk, WeCom, Mail (IMAP/SMTP), Calendar (CalDAV), Notion (official @notionhq/notion-mcp-server)

🖥️ Extensions console (issue #30, hub issue #41)

Standalone FastAPI console (fusion-plugin-console, port 8795) hosting four tabs (the two migrated verbatim from f-ecommerce, issue #30 E3, plus the capabilities hub tabs, issue #41): Connectors, Plugins·MCP, Skills, and Sub-agents. Business logic generalized — no e-commerce semantics remain.

pip install -e ".[console]"
fusion-plugin-console --port 8795     # → http://127.0.0.1:8795
  • Connectors tab — declarative JSON connector packages (rest_connector.py): install = full static validation + disk persistence; enable = runtime bridging of READ channels (GET) as connector__<id>__<op> capability plugins (auto-listed, lifecycle ENABLED); WRITE channels (POST/PUT/PATCH/DELETE) enter a human review queue and are never auto-listed; encrypted credential vault (Desk Fernet store, falls back to console-local vault.json chmod 600 when Desk config_center is absent); harness = static validation + live check of the first read operation using vault credentials.
  • Plugins·MCP tab — declarative plugin install (plugin.json manifest, no arbitrary code), tick/untick reconcile via lifecycle enable/disable, delete; remote MCP server probe & register (initialize + tools/list, candidate tools reported); per-tool tick bridges mcp__<server>__<tool> capability plugins dispatched over JSON-RPC tools/call.
  • Capability spine — derived from disk facts (connector docs + MCP ticks), rebuilt at boot via resync(); in-process registry holds no second source of truth.
  • Capabilities hub (issue #41) — the Skills and Sub-agents tabs surface the real plugin registry (console bootstraps built-ins via register_builtin(), idempotent when the inject side already registered them): skills = plugins with claude_skill capability, sub-agents = plugins with subagent capability; bridge ids (connector__*/mcp__*) stay on their own tabs. A cross-type search box matches id/name/description (case-insensitive) across all four tabs, and market groups (installed / updates / recommended) derive from the connector pack + skill marketplace catalog with semantic version comparison (1.0 ≡ 1.0.0). GUI ships zh/en toggle and follows the shell host dark/light theme.
  • Endpoints — /api/whoami, /api/capabilities, /api/hub?q=<query> (issue #41), /api/extensions/connectors[/{id}/enable|disable|harness] (DELETE removes a standalone connector — unbridge + doc + per-use policy cleanup), /api/adapters/{ref} (vault), /api/extensions/plugins[/{name}/tick], /api/extensions/mcp[/{sid}/tick], /api/hub/audit, /api/hub/connectors/{id}/revoke, /api/hub/capabilities/{cap}/used-by (issue #43), /api/registry/capabilities[/{id}] (issue #44 stable read contract), /health.
  • Marketplace backend API (issue #74) — data source for the web-shell marketplace page: GET /api/marketplace/plugins?q=&category= (id, EN+CN descriptions, source module, category, tags, icon, install count, rating, official flag, stable/beta stage, per-tenant install state), GET /api/marketplace/plugins/{id} (full description, size, changelog, source repo, and permissions derived from plugin capabilities and connector tool risk — surfaced before install), POST /api/marketplace/plugins/{id}/install|uninstall (idempotent, per-tenant state via the X-Tenant header, update = re-install when a newer version is available), and a publish path: POST /api/marketplace/submissions (manifest validation) + GET /api/marketplace/submissions?status=pending + POST /api/marketplace/submissions/{sid}/review (approve → the plugin appears in the listing as a community entry).
  • Install / authorize / update / uninstall flows (issue #42) — marketplace entries (incl. first-party packs) install as bundles from the Recommended row: skills enable, sub-agents register, connectors land as pending_auth until OAuth. Per-item enable/disable after install. Connector OAuth completes in the hub (modal): per-read-scope checkboxes (ungranted read channels are never bridged), credentials go to the encrypted vault, WRITE channels bind to a per-use confirmation policy (GET /api/hub/connectors/{id}/policy — the integration point for the cowork approval system, upstream fusion-cowork#225; until it ships, execution stays blocked by the #30 write review queue). Updates are changelog-first with opt-in new items; uninstall shows the blast radius (reverse lookup of cowork nodes referencing the bundle's capabilities) before confirmation. Bundle state persists at ~/.fusion-plugins-ecosystem/extensions/bundles.json.
  • Marketplace bundle kind (issue #42) — index entries with kind: "bundle" carry an items list (skill / subagent / connector / connector_pack / skill_package refs); index source resolves from FUSION_PLUGIN_MARKETPLACE_INDEX (local JSON or HTTPS URL, unset = builtin catalog only).
  • Authorization audit trail (issue #43) — every hub authorization action emits an audit event into the fusion-security JSONL pipeline (~/.fusion_security/audit/audit_<tenant>.jsonl, same line shape as fusion_security.engine.tenant.audit.AuditEntry — the security workbench (fusion-security#61) reads it without any code coupling; file contract only, no cross-project import). Events: hub.bundle.install (medium) / hub.bundle.item.install (low) / hub.bundle.item.enable|disable / hub.connector.oauth.grant (low, one per scope) / hub.connector.scope.policy (high, per-use WRITE policy) / hub.bundle.update / hub.bundle.uninstall / hub.connector.oauth.revoke (medium) — install/OAuth/policy events under one bundle flow share a trace_id (format fp-<hex16>) for cross-service correlation. The hub GUI shows the per-item audit history (audit button on each bundle item) with granted-scope revoke buttons.
  • Audit endpoints (issue #43) — GET /api/hub/audit (query by resource_id / resource_type / action / trace_id, read-only scan), POST /api/hub/connectors/{id}/revoke (body {"scopes": [...]} — revokes granted read scopes: re-bridges the connector with the remaining scopes, or disables it when none remain; effect lands on next load per the issue #43 contract), GET /api/hub/capabilities/{capability}/used-by (reverse lookup — cowork nodes referencing the capability, same engine as the uninstall blast radius).
  • Stable registry read contract (issue #44, PC-4) — GET /api/registry/capabilities (contract: "registry/1.0") is the single source of truth for external capability surfaces: the cowork capability marketplace (fusion-cowork#228) and the agent builder suggestions (fusion-agent-studio#529) consume it directly — no sync jobs, no forked capability caches. Each item: {id, kind (plugin|skill|subagent| connector|mcp_tool), name, version, description, enabled, auth}. Connector read channels expand from the connector doc (not just live bridges) so revoked/pending channels stay visible with auth.state = granted|pending|revoked (+ granted, granted_scopes, all_scopes_granted, hub_url — authorization actions happen in the hub, never in a consuming surface). GET /api/registry/capabilities/{id} returns the detail (same fields + per_use_scopes for connectors + in_use_by reverse lookup). Hub state changes (install/disable/revoke/uninstall) propagate on the consumer's next fetch — enabled: false items must stop being offered. Contract stability: additive field changes only, no semantic renames.
  • Env vars — FUSION_PLUGIN_CONNECTOR_DIR (default ~/.fusion-plugins-ecosystem/connectors), FUSION_PLUGIN_EXTENSIONS_DIR (default ~/.fusion-plugins-ecosystem/extensions), FUSION_PLUGIN_KEY_SALT (key-derivation salt; unset = empty in dev with a warning, fail-fast under FUSION_PROFILE=prod — no default literal, see architecture/config-conventions.md §3), FUSION_PLUGINS_ECOSYSTEM_DATA_DIR (issue #38 single-point data dir via fusion_core.config.service_data_dir; default ~/.fusion-plugins-ecosystem), FUSION_PLUGINS_ECOSYSTEM_PORT / FUSION_PLUGINS_ECOSYSTEM_CONSOLE_PORT (issue #38 port resolution via fusion_core.config.service_port), FUSION_PLUGIN_MARKETPLACE_INDEX (issue #42: marketplace index for bundle install — local JSON path or HTTPS URL; unset = builtin first-party catalog only), FUSION_PLUGIN_AUDIT_DIR (issue #43: audit JSONL sink directory, default ~/.fusion_security/audit), FUSION_PLUGIN_AUDIT_TENANT (default system), FUSION_PLUGIN_AUDIT_SINK (off drops events — test/offline isolation).

Process titles (issue #35)

Long-running entry points set their process title via setproctitle (base dependency, silent no-op fallback if unavailable): fusion-plugin-server stdio, fusion-plugin-server sse :8765, fusion-plugin-console :8795 — ps/Activity Monitor show the product name and role instead of a bare Python.

Shell module (gateway registration, issue #30 follow-up)

The console registers itself as a fusion-gateway shell module — the shell sidebar shows a Capabilities (能力中心) entry at /shell/fusion-plugins-ecosystem/ (issue #40, DD-2 hub form); stopping the console greys the entry (heartbeat expiry), restarting re-registers it. Same pattern as fusion-cowork #97/#168.

FUSION_ADMIN_KEY=<web_shell.admin_key> \
fusion-plugin-console --port 8795
  • Registration — shell_registry.py POSTs web/manifest.json (id fusion-plugins-ecosystem, upstream http://127.0.0.1:8795) then heartbeats every 15s; gateway restart (404) or key rotation (401) triggers transparent re-registration. Registration is OFF unless FUSION_ADMIN_KEY resolves (dev: missing key = empty + warning; prod: missing key = RuntimeError fail-fast). The gateway address resolves via fusion_core.config.gateway_base_url() (FUSION_GATEWAY_BASE_URL, default http://127.0.0.1:11432) — issue #38 single-point resolution.
  • fm- module key (K1/K4) — with no static api_key in the registration body the gateway issues an fm- service key (returned exactly once), persisted 0600 at ~/.fusion-plugins-ecosystem/web_module_key; heartbeats authenticate with it.
  • API auth — when a key exists (static FUSION_PLUGINS_CONSOLE_API_KEY and/or issued fm- key, dual-active), /api/* requires Authorization: Bearer / x-api-key (the gateway proxy injects the module key); with no keys configured the API stays open for loopback-only use. Static pages are session-gated at the gateway, not upstream.
  • Path-prefix aware GUI — extensions.html/shell.js resolve the API base from
  • Theme follow (#33) — embedded in the shell the iframe follows the host theme push (postMessage {type:"event", event:"theme"}, same-origin only); standalone reads the initial mode from localStorage["fusion.shell.theme"] (legacy fs_theme cookie + prefers-color-scheme fallbacks) and the sidebar toggle persists to both. location.pathname, so the same build works standalone (/) and behind the gateway (/shell/fusion-plugins-ecosystem/).

🔧 Configuration (one-click panel)

EcosystemConfig — all toggles default to True for native Claude compatibility.

Toggle Controls Off behavior
enable_claude_mcp list_mcp_tools, invoke_mcp_tool returns [] / isError=True
auto_export_claude_skill export_skills returns []
default_mount_compressor export_default_mounted_skills returns []
subagent_timeout_destroy dispatch_subagent no unload on timeout
enable_volcengine_claude_plan volcengine credential store/get refused / None
enable_mixed_quantization mlx_visual_backend raises RuntimeError
mcp_transport MCP transport type stdio / sse / http
sandbox_default_mode Default sandbox mode inline / process
max_token_records Max token meter records pruning threshold
token_persist_path Token persistence file None = in-memory
enable_connector_framework External MCP connector install/bridge install raises RuntimeError
connector_persist_path Connector registry persistence file None = in-memory
connector_marketplace_index Marketplace index (local JSON path or HTTPS URL) None = builtin catalog only
vram_limit_mb Total vRAM budget (synced to DeskRuntime.vram_total_mb) 0 = unlimited
max_concurrent_plugins Inline execution concurrency gate (asyncio.Semaphore) unbounded
log_level Root logger level (applied on MCPServer init) INFO
subagent_timeout_seconds Subagent execution timeout 600
max_auto_restart Crash auto-restart cap 3
heartbeat_stale_seconds Heartbeat staleness threshold 120
from fusion_plugins_ecosystem import EcosystemConfig

# All-on by default
config = EcosystemConfig()
# Disable MCP exposure
config.enable_claude_mcp = False
# Persist via Desk config center
d = config.to_dict()
restored = EcosystemConfig.from_dict(d)

🛠️ Pain points solved

Pain point (from PRD) Solution
Subagent runs 40 min, zero token consumption, no logs TokenMeter warns on wall>60 ∧ total=0; all logs via DeskRuntime.log
vRAM contention across plugins DeskRuntime.acquire_vram enforces vram_total_mb budget ledger
MCP port conflicts fusion-cowork single MCP gateway; MCPExporter multiplexes
Subagent hangs, no unified restart PluginLifecycle timeout meltdown + _maybe_restart (≤ MAX_RESTART)
Heartbeat stall PluginLifecycle._watch_loop flags HEARTBEAT_STALE → TIMEOUT

🛡️ Hardening (audit P0–P3)

A full architecture audit (audit/fusion-plugins-ecosytem--audit-result-0830.md) surfaced 20 P0–P3 findings; all fixable in-repo are addressed:

ID Finding Fix
A3 Studio config keys semantically reversed log_level/vram_limit_mb/max_concurrent_plugins map to real backend fields (no longer to mcp_transport/mcp_port/max_auto_restart)
R6 SSE/HTTP zero-auth + plaintext API keys Bearer-token auth (FUSION_PLUGIN_AUTH_TOKEN env, constant-time compare); API keys at-rest Fernet-encrypted (enc: prefix, plaintext passthrough for back-compat)
A4 config/install zero-persistence plugins/config.set, plugins/install, plugins/uninstall persist to Desk config_center; MCPServer.start() restores installed plugin set
R1 PROCESS sandbox _DeskProxy no-op Worker → host resource-proxy RPC (acquire_vram/release_vram/mlx_chat/get_api_key/check_file_permission) over stdin/stdout, thread-safe future resolution
A2 config → lifecycle break, dead fields MCPServer/MCPHandler inject config into PluginLifecycle; timeout/restart/heartbeat thresholds config-driven with class-constant fallback
A5 token_meter ↔ config break MCPHandler/MCPServer construct TokenMeter with max_token_records/token_persist_path from config
R2 inline unbounded thread pool asyncio.Semaphore (max_concurrent_plugins) gates to_thread inline execution
R3 _maybe_restart no backoff exponential backoff min(2**(n-1), 60) (skipped when no config, preserving test immediacy); double-check plugin existence post-backoff; enable failure → CRASHED
R4 token_meter full-rewrite per record throttled persistence (batch/interval) + explicit flush()
R5 per-handler rate limit session + rate-limit state shared on DeskRuntime (cross-handler single source, lock-guarded)
R7 log lock contention get_logs snapshots under lock, filters outside
E1 spawn passes empty config _invoke_sandbox forwards config.to_dict() to worker
E2 cpu_limit decorative RLIMIT_CPU enforced in worker (SIGXCPU on exceed)
E3 unload fire-and-forget kill task tracked in _pending_kill_tasks to prevent GC
E4 dispatch_subagent uncaught enable exception enable errors caught, logged, returned as failed state
E5 version string compare not semver _version_key tuple parse ("1.0" == "1.0.0")
E6 in-function repeated import json hoisted to module top (jsonrpc.py, claude_gateway.py)
E7 claude_adapter legacy double logic SSOT build_skill_dict in skill_adapter.py, legacy adapter delegates
E8 tests mask config break _make_handler accepts config; wiring test asserts config drives lifecycle/token_meter
A1 zero cluster/multi-node awareness out of scope — requires cross-project distributed state layer; upstream issue fusion-cowork#79

Remote transport auth

SSE/HTTP transports are remote-capable and therefore require a Bearer token when exposed beyond localhost. Set it via environment variable (never persisted to config):

FUSION_PLUGIN_AUTH_TOKEN="$(openssl rand -hex 32)" fusion-plugin-server --transport http --port 8765

Requests without Authorization: Bearer <token> get 401 Unauthorized. stdio transport (local subprocess) is exempt.

🖥️ fusion-studio integration

fusion-studio consumes this package over HTTP JSON-RPC. The SwiftUI client (PluginBridge.swift) POSTs {"jsonrpc":"2.0",...} to http://<host>:<port>/rpc and reads json["result"] as a dict with named keys (not an array). The MCPHandler.handle dispatcher exposes 15 plugins/* methods whose result envelopes are shaped to match each PluginEcosystemModels.swift fromDict contract exactly:

Method Result envelope Studio model
plugins.ping {pong} health check
plugins/list {plugins[]} PluginListItem (id/name/category/version/description/author/enabled/installed)
plugins/install {ok} enable plugin
plugins/uninstall {ok} disable + unload
plugins/config.get 7 Studio-named keys EcosystemConfig (sandbox_mode/auto_update/max_concurrent_plugins/log_level/token_budget/vram_limit_mb/mcp_enabled)
plugins/config.set {ok} single key-value pair (params IS the pair)
plugins/states {states[]} PluginStateInfo (id/plugin_id/state/pid/start_time:str/uptime:int/error_count/last_error)
plugins/state.get state dict PluginStateInfo
plugins/state.list {plugins[]} filtered by state
plugins/token.records {records[]} TokenRecord (id/plugin_id/prompt_tokens/completion_tokens/total_tokens/timestamp:str/model)
plugins/token.prune {ok} prune by max_age_seconds
plugins/vram.usage {total_mb,used_mb,free_mb,by_plugin[]} VRAMUsage + VRAMPluginEntry (allocated_mb/peak_mb)
plugins/logs.stream {entries[]} PluginLogEntry (id:str/plugin_id/level/message/timestamp:str)
plugins/mcp.sessions {sessions[]} MCPSession (id/session_id/plugin_id/server/status/tool_count/connected_at:str)
plugins/mcp.sessions.prune {ok} prune by max_age_seconds

The backend EcosystemConfig uses different field names than Studio; the plugins/config.* handlers project between the two namespaces. MCPServer auto-registers built-ins (caveman_compress) on start(), so plugins/list is discoverable without manual registration. Node discovery (desk.list_nodes()) returns [] when fusion-cowork is not installed — the integration path requires fusion-cowork to host the /rpc endpoint (upstream gap, tracked separately).

MCPServer.start() blocks on an instance-level stop_event for all transports (stdio/sse/http), so the standalone CLI (fusion-plugin-server) stays alive until stop() or SIGTERM — previously sse/http returned immediately and the process exited. Verified: fusion-plugin-server --transport http stays alive and /rpc returns caveman_compress v0.3.4 and {pong: true}.

🧪 Testing

.venv/bin/python -m pytest --cov=fusion_plugins_ecosystem --cov-report=term-missing -q

Latest run: 747 passed.

Test file Tests Covers
test_desk_runtime.py 30 vRAM / logging / permissions / API keys / MLX / node bridge / scheduler bridge
test_lifecycle.py 40 load/enable/disable/unload/execute/timeout/crash/restart/watcher/idempotency + _enable_with_retry (vRAM transient retry, permanent-error no-retry)
test_mcp_exporter.py 13 list_tools / call_tool / gateway_info / manifest_to_mcp_tool
test_token_meter.py 22 TokenRecord / record / measure / summary / stuck-subagent warning / WAL append+compaction (round-trip, crash-recovery dedup, threshold)
test_claude_adapter.py 13 export_one / export_all / export_default_mounted / param types / enum / required
test_claude_gateway.py 45 three-layer compat / forward-reverse / auth / config toggles / token integration
test_config.py 9 defaults / to_dict / from_dict / roundtrip / partial / unknown key
test_registry_full.py 15 register / unregister / list / category / default_mounted / enum values
test_caveman.py 22 _compress_text / caveman_compress / CAVEMAN_MANIFEST fields
test_registry.py 13 (legacy) registry + adapter + exporter + caveman integration
test_hook_adapter.py 8 HookAdapter event mapping / capability filtering
test_transport_server.py 27 SSE/HTTP/stdio transport + MCPServer start/stop lifecycle + CLI main() + SSE queue-bound drop-on-full
test_jsonrpc_plugins.py 25 Studio plugins/* 15-method dict envelopes + exact-key matching + config-driven wiring (E8)
test_metrics.py 20 observability counters/gauges / Prometheus render / label escaping / /metrics endpoint / path counters (lifecycle/MCP/sandbox/vram/session)
test_load.py 8 load/concurrency safety: lifecycle concurrent execute + max_concurrent semaphore, metrics thread-safety (counter/gauge/render), token-meter high-freq + concurrent record, PROCESS sandbox spawn storm no-leak
test_cluster_bridge.py 9 multi-node distributed state: cross-node plugin enable/disable + vRAM visibility, stale-node failover evict (clears state/vRAM), heartbeat keeps-alive, cluster_bridge singleton sync, lifecycle enable/disable cluster sync, DeskRuntime cluster query methods, cluster-disabled no-op degradation
test_soak.py 8 long-run stability: token-meter cap holds under 50k records, log buffer deque cap, session _MAX_SESSIONS LRU cap + calls-list bound, counter 100k monotonic inc no-drift (labeled buckets), lifecycle 500 sustained execute no-residual, token-meter 8k record + query aggregate consistent
test_logging_setup.py 10 structured JSON logging: JsonFormatter output + correlation_id propagation (set/reset/contextvar), configure idempotent + extras + exc_info + non-serializable fallback (P3-6)
test_connector.py 25 connector framework: pack validation/roundtrip, registry bridge + MCP export, HIGH_RISK approval gate, persistence roundtrip, credential resolution, real stdio MCP client subprocess round-trip, local HTTP JSON-RPC round-trip
test_connector_packs.py 10 first-party packs structural validation, unique ids/tool names, schema shape, risk-level conventions (read-only=LOW, write=MEDIUM/HIGH), Feishu acceptance shape, lifecycle load of bridged tools
test_marketplace.py 13 builtin catalog, JSON index load + same-id override, HTTPS-only constraint, install builtin/local-source/skill-package, uninstall, list_installed, config wiring
test_rest_connector.py 15 declarative connector docs: validation, read/write channel split, persistence roundtrip, execution contract vs local HTTP server, JSONPath-lite extraction, {var} rendering
test_extensions_console.py 26 console backend: connector install/enable/disable/harness, credential vault (Desk round-trip + local Fernet fallback), bridged op execution, MCP intake probe/register/tick/call, plugin tick/remove/install, resync rebuild, spine derivation, standalone lifecycle bootstrap
test_console_app.py 6 FastAPI console: whoami/capabilities, connector full flow (install→vault→enable→disable→harness), MCP flow, plugins flow, static serving
test_hub.py 17 capabilities hub (issue #41): builtin bootstrap, four-tab classification, cross-type search incl. recommended facet, market groups, key isolation, /api/hub endpoint
test_install_flow.py 22 bundle install/OAuth/update/uninstall flows (issue #42): per-item states, pending_auth, scope grants bridging, per-use policy, changelog-first update, uninstall blast radius
test_registry_contract.py 4
test_audit_flow.py 9 authorization audit (issue #43): install/OAuth/update/uninstall events + trace-id linkage + JSONL contract, scope revoke re-bridge/disable, used-by reverse lookup, HTTP endpoints

⚠️ Technical constraints

  • Cannot run standalone — process hosting, permissions, logs, resources all depend on fusion-cowork
  • Python ≥ 3.11 — aligned with fusion-cowork
  • Mac M-series native — depends on fusion-mlx Metal/MLX acceleration
  • No direct fusion_cowork internal imports — go through DeskRuntime

📄 License

Apache License 2.0 — part of the Fusion-MLX Apple Silicon local AI ecosystem.

Metadata

Release files for fusion-plugins-ecosystem 0.11.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fusion-plugins-ecosystem 0.11.0
File Size Uploaded Provenance Actions
fusion_plugins_ecosystem-0.11.0.tar.gz 275.0 kB With provenance Details for fusion_plugins_ecosystem-0.11.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for fusion-plugins-ecosystem 0.11.0
File Interpreter ABI Platform Actions
fusion_plugins_ecosystem-0.11.0-py3-none-any.whl Python 3 none any Details for fusion_plugins_ecosystem-0.11.0-py3-none-any.whl

Total release size: 458.7 kB

Release files / fusion_plugins_ecosystem-0.11.0.tar.gz

Download URL fusion_plugins_ecosystem-0.11.0.tar.gz
Size 275.0 kB
Tags Source
SHA-256 checksum
How to use checksums
20b4597d58d3fd2682f927cdd20cb9afdc63ecb3d22db828cbe7f42a3f5f2f10
BLAKE2b-256 checksum
How to use checksums
1e39973369a447cae20b5791adf3ccd853110f08aedb05374f74fbb7112911a0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Release files / fusion_plugins_ecosystem-0.11.0-py3-none-any.whl

Download URL fusion_plugins_ecosystem-0.11.0-py3-none-any.whl
Size 183.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
25a7d033c778f5f7854017fc2f0c45293f127756b8810d0b72a809ce6ef15b4c
BLAKE2b-256 checksum
How to use checksums
3cfd69a749fdbe3534056e7c598a80a2cf8007ee30511b2b996b087ce5ef763b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Security for fusion-plugins-ecosystem 0.11.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for fusion_plugins_ecosystem-0.11.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page