5.8 KiB
Plugin platform implementation review
Baseline: main 0256e7471d66bbbca077c361ef379d7b11ce8465 (2026-10-26).
Existing capabilities and gaps
| Area | Implemented source | Remaining boundary |
|---|---|---|
| Contract, SDK, package CLI | packages/plugin-contract/schema, packages/plugin-sdk, packages/plugin-cli |
Internal API 0.1.0-internal; no public API stability promise |
| Runtime | electron/plugins/browserPluginRuntime.cjs, utilityPluginRuntime.cjs, hostBootstrap.cjs |
Entire host remains development opt-in; advanced utility is ambient Node authority, not a fine-grained sandbox |
| Permissions | permissionEngine.cjs, hostRpcRegistry.cjs, secureCapabilities.cjs |
Broker checks at privileged boundary; unsigned principal bound to package digest; verified publisher/distribution not implemented |
| UI contributions | contributionService.cjs, components/plugins, SettingsPluginsTab.tsx |
Commands, menus, keybindings, settings and views exist; current Settings page is contributed settings, not a package manager/marketplace |
| Terminal | terminalProviderService.cjs, terminalDataPipelineService.cjs |
Completion/link/visual providers and lifecycle; interceptors require privileged utility placement; not arbitrary terminal object access |
| Connection, authentication, importer | extensionProviderService.cjs, application/state/pluginExtensionBridge.ts |
Existing operation-bound provider integration; not general vault/SFTP/clipboard CRUD |
| Sync | pluginSyncSidecarService.cjs, application/pluginSyncSidecarBridge.ts |
Opt-in non-secret settings and account/CRDT sidecars; ordinary KV is local, package code/permissions/secrets are not cloud authority |
| Compatibility | plugin-cli/src/compatibility.ts, packageStore.cjs, runtimeSupervisor.cjs |
Install/start checks existed; startup reconciliation and lazy re-enable checks missing |
| Local package | packageStore.cjs, CLI pack, first-party examples/plugins/hello-netcatty |
Immutable snapshot, hash/integrity validation and safe extraction exist; no ordinary import management UI |
| Distribution | No public catalog implementation | Version/hash/pinned README, review workflow, manual update UI still needed |
Historical merged steps: #2276 contract/SDK; #2303 runtime; #2315 permission/security;
#2324 UI contributions; #2338 terminal providers; #2402 privileged terminal pipeline;
#2413 connection/auth/importers; #2713 sync; #2748 and #2752 sync follow-up fixes.
The repository AGENTS.md runtime section describes an earlier phase and must not
be mistaken for a complete current capability inventory. No repository .agents/skills
directory was present at this baseline.
Small implementation slices
- Reconcile host/API/features compatibility before contribution enumeration; disable incompatible plugins and retain package/data, record the reason; block lazy re-enable. Do not auto-enable after a host downgrade.
- Reuse the existing Settings Plugins tab and management IPC for installed packages, manifest-derived permissions, version/hash and lifecycle actions; local import starts disabled for review. Keep native permission mediation.
- Add a lightweight first-party catalog and pinned safe README detail renderer, shared package verification, digest-bound manual update flow and author docs. Do not introduce remote accounts, reviews, payments or a new repository.
- Reproduce the actual Electron flow with synthetic data and the first-party sample; transfer source/build instructions if GUI is unavailable here.
Decisions and explicit release gates
User approved public source plus a clear license for catalog entries, and manual confirmation of plugin updates. Private local packages remain separate.
User-approved public v1 eligibility: browser runtime only. Utility Node, native companions and raw terminal interceptors retain the development preview path. This excludes advanced provider implementations requiring Node/native binaries; ordinary browser contributions, broker-backed networking and providers remain possible. No existing local advanced development path is removed.
After product review, normal Settings now admits browser-only packages. The
NETCATTY_PLUGIN_DEV=1 flag gates advanced local packages only; their existing
permission prompts remain mandatory. Shared host/UI classification preserves
browser-first placement for dual-entry packages while excluding them from normal
admission. Native acceptance remains pending. Passing tests is not proof of
security isolation. Do not describe utility processes as broker-constrained.
A future KV sync feature needs an explicit manifest opt-in schema, size limits, namespace and schema-version migrations, deterministic conflict/deletion rules, account switching semantics and secret exclusion. It is deliberately not silently enabled in this iteration. Reuse existing settings sidecars for small preferences.
Catalog entries should bind ID, repository, license, author, version, commit, artifact SHA-256 and URL, platform/engine ranges, permissions and README revision. A hash mismatch must fail rather than fall back to latest. README must not execute HTML or automatically fetch remote media. Directory PR checks are a bounded review process, not a security certification or a guarantee that maintainers will repair third-party plugins.
Validation at the implementation stage
The full repository TypeScript check has 773 diagnostics on both the frozen main
and this implementation. After normalizing worktree paths and line shifts, no
new diagnostics were introduced. This existing debt includes plugin integration
types and should be addressed in a separate API-drift cleanup rather than being
hidden by changing public contracts opportunistically. Canonical contract drift
checking and plugin runtime tests pass for this implementation; native Electron
UI acceptance is tracked separately in native-acceptance.md.