Skip to content

feat(plugins): install and remove plugins from Settings - #22

Draft
ashx-j wants to merge 12 commits into
mainfrom
feat/plugins-phase-7
Draft

feat(plugins): install and remove plugins from Settings#22
ashx-j wants to merge 12 commits into
mainfrom
feat/plugins-phase-7

Conversation

@ashx-j

@ashx-j ashx-j commented Oct 30, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

Phase 7 of the plugin system roadmap (#3, phase issue #11), first part. It builds on #21, so until #14 to #21 merge this diff also shows their commits.

Until now a plugin had to be copied into the data folder by hand or listed as a dev folder in plugins.json. Now people can add and remove plugins from Settings → Plugins, and agents can do it when asked.

  • Install. plugins.install takes a folder on the server or a git repository with an optional branch or tag. The host fetches it into a staging folder, checks its manifest, and moves it into plugins/<id> with a rename. If a reinstall fails, the previous version stays in place and starts again. The plugin is enabled and started once it is installed.
    • A folder is copied, never linked, so later changes to the source don't affect the installed plugin.
    • Git runs git clone --depth 1 with prompts off and only the https, http, ssh, git and file protocols allowed. The .git folder is removed afterwards.
    • A plugin id that a dev folder already provides is refused with a message saying so.
  • Uninstall. plugins.uninstall stops the plugin, deletes its folder and removes it from plugins.json. Its settings, secrets and storage are kept unless the user asks to delete them. Dev folder plugins can't be uninstalled; the message says to remove them from plugins.json instead.
  • Settings UI. An "Add plugin" row on the Plugins page with the 2 sources, and a remove action on installed plugins with a "delete its settings and stored data" checkbox. Both need settings:write, like enabling a plugin.
  • Agent tools. t3_plugins_install and t3_plugins_uninstall, gated as writes and advertised only once a plugin is installed, like the other t3_plugins_* tools.
  • Compatibility was already in place from Phase 1: a plugin whose engines.t3 excludes the running server fails with the reason shown on its row, and it can now be uninstalled.
  • Docs. A new user guide, docs/user/plugins.md, linked from the docs index.

Changes from the roadmap (issue #11 is updated):

  • Not built yet:
    • npm installs. The server has no tar library, and adding one or shelling out to tar is a separate decision.
    • Update checks and updates. Reinstalling from the same source updates a plugin today.
    • The mobile install dialog. Mobile still has no plugin settings screen from Phase 2.
    • The example plugins repository. Creating ashx-j/t3code-plugins is a public repository under Ash's account, so I left that for him to decide.
  • Install shares the host's lifecycle lock only for the stop-and-swap step. Copying and cloning happen first, outside it, so other plugins keep starting and stopping meanwhile.

Measurements:

  • Nothing runs at startup: there is no update check yet.
  • An install runs in its own request's fiber, so other WebSocket requests are still served. I did not measure installing while a turn streams.

Screenshots:

GitHub's CLI can't upload images, so 2 screenshots are in the T3 thread for this work instead: the "Add plugin" form, and the Plugins page after installing http-plugin. They still need to be dragged into this description during review.

Test plugins: the existing hello-plugin and http-plugin fixtures, installed from their folders and from a local git repository.

Verification:

  • A new PluginHost.test.ts case installs hello-plugin from its folder and checks it is active. A reinstall from a folder with a broken manifest fails, and the old version keeps running with its files in place. Uninstalling with data removal deletes the folder and the plugin's row.

  • PluginMcpTools.test.ts checks the 2 new tools are advertised with the others. commandPermissions.test.ts lists the 2 new methods as settings:write.

  • In a browser against a dev server on seeded data:

    • I installed http-plugin from its folder, saw it active, and removed it with its data; the folder and its plugins.json entry were gone.
    • I then installed it from a local git repository (file://) and checked the .git folder was removed.

  • vp run check:changed passed.

  • Not verified: installing from a remote git host, and the mcp-tool-use eval for the 2 new tool descriptions, which needs paid agent turns.

  • SDK README. packages/plugin-sdk/README.md covers the manifest, both halves of a plugin, the Vite preset and dev folders, for plugin authors.

Review: an adversarial review of #18 to #22 found issues in this PR; the fixes are in #23.

PR filed by Claude Opus 5.5 in Claude Code through T3 Code.

This was referenced Oct 30, 2026
Open
Open
@github-actions github-actions Bot added the vouch:trusted PR author is trusted by repo permissions or the VOUCHED list. label Oct 30, 2026
@ashx-j ashx-j mentioned this pull request Oct 30, 2026
Open
@ashx-j
ashx-j force-pushed the feat/plugins-phase-7 branch from 2f978e2 to f7ac82d Compare October 30, 2026 22:31
This was referenced Oct 30, 2026
Draft
Draft
Draft
Draft
Draft
Draft
Draft
ashx-j and others added 12 commits October 31, 2026 21:22
@ashx-j @claude
feat(contracts): plugin manifest, state and RPC schemas, plugins capa…
a89f5c8 
…bility flag

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ashx-j @claude
feat(plugins): plugin SDK skeleton, hello fixture and internal doc
c1e79bd 
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ashx-j @claude
feat(plugins): server plugin host
e25eab1 
PluginHost discovers installed and dev plugins, loads enabled CommonJS
entries after the server is listening, and hands each a Promise-based API
for logging, settings, storage, RPC methods and channels. Failures mark the
plugin failed and never stop the server. Settings live beside T3's state
with secrets in the server secret store; storage is a lazily opened SQLite
file. Eight plugins.* WebSocket methods manage plugins, and the environment
advertises plugins: true.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ashx-j @claude
fix(plugins): harden the plugin host lifecycle and access checks
2918b9f 
An adversarial review found that reloading one plugin left plugins whose
folders vanished running, that a caller disconnecting mid-disable left a
plugin half torn down but still routed, that a misspelled access level
made a write method callable by read-only sessions, and that reload kept
old code for symlinked plugin folders. Lifecycle changes now run in the
host's scope, vanished plugins are stopped, access must be read or write,
and discovery resolves real paths. Activation and cleanups get deadlines,
calls stop routing before teardown, and plugins.json keeps unknown keys.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ashx-j @claude
feat(plugins): manage plugins and their settings in Settings
73a5e9b 
Settings gains a Plugins page for the selected environment: each plugin
with its status, failure, enable switch and reload, plus a settings form
generated from the manifest's JSON Schema with write-only secret fields
and a JSON fallback. The page follows plugins.subscribeStates only while
open; the form model lives in client-runtime for the later mobile screen.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ashx-j @claude
feat(plugins): server plugin API for events, threads, tools, scheduli…
7aae578 
…ng and send hooks

Plugins can now follow stored orchestration events by type, read and act
on threads and projects, run scheduled work, see and extend outgoing
messages before they are sent, offer MCP tools to agents and serve HTTP
routes under /api/plugins/<id>, and read the server's version, descriptor
and redacted settings. The send hook runs in ThreadManagementService.dispatch
with a 2 s deadline and fails open; with no hooks it is one Ref read.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ashx-j @claude
fix(plugins): keep slash commands and event order intact, gate plugin…
c2d9362 
… writes

An adversarial review found that a send hook appending to /goal clear
turned it into setting a goal, that the SDK promised a veto nothing
honoured, that several event types merged out of sequence order, that a
schedule could outlive its plugin, and that plugin write tools skipped the
caller's mode limits. Hooks now skip slash commands, veto is gone from the
SDK, multi-type event streams stay ordered, schedules and hooks stop on
the deactivation signal, API calls end after cleanups, plugin write tools
need full access like environment writes, and tool schemas must be objects.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ashx-j @claude
feat(plugins): web plugin loader, settings panels and right panels
9cf43ba 
Plugins could only run on the server. The server now serves each active
plugin's web bundle, and the web app loads it once an active plugin has a
web part: a starter follows plugin state after idle, and the loader fetches
bundles with the connection's credentials and imports them from blob URLs.
Bundles share the app's React, atom hooks and UI kit through a host object.

Plugins can add right panels, listed in the add menu and the empty panel,
and replace their generated settings form. An unloaded plugin's panel shows
"Plugin not active" with a close button. The desktop CSP allows blob scripts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ashx-j @claude
feat(plugins): palette, keybinding and composer commands from plugins
645cf7e 
Web plugins could add panels but nothing users could run from the
keyboard. Plugins can now register command palette commands that users
bind as plugin.<pluginId>.<commandId>, and slash commands in the composer
that run plugin code. They can also navigate and load files from their
assets folder, which the server serves under /api/plugins/<id>/assets/*.

The SDK gains a Vite preset that builds web.js against T3's React and UI
kit, keeping only the names a plugin uses, and typed UI components.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ashx-j @claude
feat(plugins): timeline renderers, banners, code blocks and themes fr…
5782adc 
…om plugins

Web plugins could add panels and commands but not change how T3 looks or
how conversations read. A plugin's themes/ folder is now published through
the environment theme service, so its themes reach every client. Web
plugins can show composer banners, draw their own MCP tool calls in the
timeline, draw fenced code of a language in chat messages, and inject
styles. Everything is removed when the plugin unloads.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ashx-j @claude
feat(plugins): run-completed hook, richer send hook and agent plugin …
6738076 
…tools

Plugins could see a message before it was sent but not what happened
after, and agents could list plugins but not use them.

turns.afterRunCompleted delivers every ended run in order, saving its
position in the plugin's storage so runs that end while the plugin is off
arrive when it starts. turns.beforeDispatch now gets the message id,
attachment summaries and the requested model. Agents get
t3_plugins_invoke and t3_plugins_set_enabled, gated as writes and only
advertised once a plugin is installed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ashx-j @claude
feat(plugins): install and remove plugins from Settings
85d0e4f 
Plugins had to be copied into the data folder by hand or listed as dev
folders. plugins.install now takes a folder on the server or a git
repository, stages it, checks the manifest and swaps it into place with a
rename, keeping the previous version if anything fails. plugins.uninstall
stops and deletes a plugin, keeping its data unless asked otherwise.

Settings → Plugins gets an Add plugin form and a remove action, agents get
t3_plugins_install and t3_plugins_uninstall, a user guide explains it, and
the SDK gets a README for plugin authors.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ashx-j
ashx-j force-pushed the feat/plugins-phase-7 branch from f7ac82d to 85d0e4f Compare October 31, 2026 21:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

size:XXL vouch:trusted PR author is trusted by repo permissions or the VOUCHED list.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@ashx-j