Feature proposal: a rich, capability-based plugin platform

[airtonix]

Feature proposal: establish a rich plugin platform for hrdx

Summary

I’d like to propose a first-class plugin platform for hrdx.

The goal is to let external tools integrate with hrdx workspaces, tabs, panes, agents, and UI surfaces without requiring plugins to run inside the hrdx process or depend on private Go types. Plugins should be independently versioned, supervised, capability-limited participants that communicate with hrdx through a stable protocol.

This proposal is intentionally trying to follow the plugin protocol and extension shape established by Zot, where that provides a useful baseline for manifests, external plugin processes, registration, lifecycle, and plugin-owned TUI views. hrdx would adapt those ideas to its own PTY, holder, layout, persistence, and Bubble Tea ownership boundaries rather than importing Zot internals or coupling to its implementation.

This would extend hrdx beyond custom agent harness registration while preserving its core identity:

• every terminal pane remains backed by a real PTY;
• holder sessions continue to own persistence for terminal processes;
• Bubble Tea remains the owner of live UI state;
• plugin failures cannot take down hrdx or existing panes;
• plugin state does not become part of core workspace state;
• the binary remains portable with a small dependency footprint.

Proposed plugin model

A plugin would be a package containing:

• a versioned manifest;
• a stable globally namespaced ID;
• an executable entrypoint;
• declared contributions;
• requested capabilities;
• optional configuration schema and documentation.

The manifest would describe what the plugin provides, but would not itself execute arbitrary shell hooks. hrdx would be able to discover, validate, inspect, enable, or disable packages without starting them.

Possible discovery locations would include:

1. an explicitly configured project or instance directory;
2. the user's hrdx plugin directory;
3. platform-specific data directories;
4. an optional development path supplied on the command line.

Discovery should be deterministic and produce useful diagnostics for malformed manifests, duplicate IDs, unsupported protocol versions, missing entrypoints, and permission errors.

What plugins could provide

The initial contribution model could support:

• commands and contextual actions;
• workspace, tab, and pane metadata;
• filtered lifecycle and selection events;
• status contributions;
• notifications;
• pull-based providers for search, diagnostics, or workspace data;
• private namespaced storage;
• workspace/project integrations;
• metadata and workflows around existing agent panes;
• constrained plugin-owned TUI views.

Plugin-owned views would be hosted inside hrdx-owned floating frames or grid-cell frames. The plugin could own the view's content, internal layout, rendering, and content-area input, while hrdx would retain ownership of:

• frame placement and sizing;
• clipping and z-order;
• cleanup;
• mouse hit testing;
• settings;
• menus;
• footer input.

A plugin view would not be a terminal pane. It would not have a PTY, shell process, holder session, or terminal persistence identity.

What plugins would not receive

Plugins would not receive:

• direct access to ui.Model;
• Bubble Tea messages or commands;
• terminal emulator internals;
• holder protocol access;
• raw state.json;
• unrestricted access to terminal contents;
• arbitrary rendering access to the hrdx screen;
• arbitrary process spawning by default;
• guaranteed delivery of every event.

Plugins would use semantic protocol objects rather than screen scraping, title-string conventions, or private hrdx implementation details.

External process and protocol boundary

Plugins should run as supervised external processes rather than embedded Go plugins.

The initial transport could be local stdin/stdout using newline-delimited JSON, following the practical shape of Zot's external plugin communication while keeping hrdx's protocol independently versioned. A bidirectional protocol would provide:

• protocol and schema negotiation;
• hello, ready, and graceful shutdown messages;
• request IDs and concurrent in-flight calls;
• cancellation and deadlines;
• structured errors;
• progress notifications;
• bounded message sizes;
• subscription filters and scopes;
• heartbeat or liveness handling;
• contribution registration and cleanup.

The existing hrdx control socket should remain separate. A plugin connection should be associated with a known package identity and an hrdx-issued session or transport credential.

Future Unix socket or Windows named-pipe support could be added if independently managed plugin daemons, multiple hrdx instances, or restart-surviving services create a concrete need. It should reuse the same protocol and capability broker rather than create a second plugin API.

Capability and security model

Requested capabilities would never be granted automatically.

The host should mediate every plugin operation through a capability broker. Capabilities should distinguish:

• read versus mutation;
• instance, workspace, tab, and pane scope;
• ordinary metadata versus sensitive terminal content;
• one-shot calls versus long-lived subscriptions;
• host-owned operations versus plugin-private storage.

Potential capability families include:

workspace.list
workspace.read
workspace.observe
tab.read
pane.read_metadata
pane.read_title
pane.read_screen
host.events.subscribe

ui.command.contribute
ui.action.contribute
ui.status.contribute
ui.view.contribute
ui.view.input
ui.notification

workspace.create
workspace.close
tab.create
pane.create
pane.close
pane.send_input
pane.resize

process.spawn
storage.plugin_private
storage.workspace_scoped

High-risk operations such as sending input to a shell or agent, creating panes, reading terminal content, or spawning processes should require separate explicit grants.

Capability checks must happen at request time, not only during the initial handshake.

Failure and lifecycle requirements

A plugin should move through an explicit lifecycle such as:

discovered -> validated -> disabled/approved
approved -> starting -> handshaking -> ready
ready -> degraded -> ready
ready -> stopping -> stopped
starting/ready -> failed

The host should provide:

• lazy activation by default;
• bounded restart attempts and backoff;
• explicit start, stop, and restart;
• graceful shutdown;
• contribution cleanup on disconnect;
• cancellation of pending work;
• sanitized diagnostics;
• no orphaned panes, holder sessions, or layout references;
• continued hrdx operation when a plugin crashes or misbehaves.

A plugin crash should remove the plugin's contributions and pending requests without affecting existing workspaces, PTYs, agents, or holder sessions.

Persistence and compatibility

Only host-owned plugin preferences should be persisted with hrdx state, for example:

{
  "plugins": {
    "example.git-tools": {
      "enabled": true,
      "grants": [
        "workspace.read",
        "ui.status.contribute"
      ],
      "config": {
        "show_clean": false
      }
    }
  }
}

Live connections, process IDs, subscriptions, callbacks, and plugin-private data should remain outside state.json.

Existing state files must remain loadable. Missing plugin fields should default safely, unknown optional fields should be ignored, and unsupported optional contributions should degrade without affecting core hrdx state.

Suggested first milestone

The first milestone should freeze the public design boundary before runtime implementation:

1. define the manifest schema;
2. define stable IDs and version fields;
3. define protocol framing and message limits;
4. define the handshake and error vocabulary;
5. define capability names and scope terminology;
6. define plugin discovery precedence;
7. define host-owned persistence rules;
8. provide valid and invalid manifest fixtures;
9. document compatibility expectations, including which parts are intended to remain compatible with Zot's plugin protocol.

This milestone would not launch plugins or change user-facing behavior. It would give maintainers and plugin authors a stable contract to review before implementation begins.

Questions for discussion

1. Does the external-peer and capability-broker boundary fit hrdx's long-term direction?
2. Does this proposed alignment with Zot's plugin protocol provide a useful compatibility target, without coupling hrdx to Zot internals?
3. Is local NDJSON over supervised stdin/stdout the right initial transport?
4. Which contribution should be implemented first: commands, status, workspace metadata, providers, or plugin-owned views?
5. Which capabilities should be considered sensitive enough to require explicit per-plugin approval?
6. Should plugin discovery and diagnostics ship before plugin execution?

The central design rule is:

A plugin declares what it contributes, a supervised external peer performs the work, and a capability broker controls every interaction with hrdx.

[airtonix]

I based this proposal from a clanked plan here https://gist.github.com/airtonix/a038219ae8f8793d2b6d0fcb1d48272f

[patriceckhart]

@airtonix Thank you for this contribution! I like the concept and would like to create a draft.

[patriceckhart]

@airtonix Thanks for the thorough proposal. It is now implemented on main and shipped in 0.0.45. Here is what landed, where it follows your plan, and where it deliberately diverges.

What is in

Plugins are supervised external processes speaking newline-delimited JSON over stdin/stdout, exactly the transport you suggested. The protocol is independently versioned (manifest schema 1, wire protocol 1) and does not claim zot compatibility. zot was the design inspiration, not a compatibility target.

Everything is behind explicit flags: --plugins enables the runtime, --plugin-views additionally enables views. A fresh install runs nothing.

Discovery is separate from execution. hrdx plugins list and doctor inventory packages and report diagnostics without launching anything. Execution requires hrdx plugins approve --package PATH --trust, which binds the approval to the canonical package path plus a SHA-256 digest of every file. Any change to the package needs reapproval. Duplicate IDs invalidate every claimant rather than picking a winner.

Capabilities are named grant given at approval time and rechecked on every request, never inferred from the manifest. The vocabulary is close to your list: ui.action.contribute, ui.provider.contribute, ui.notification, ui.status.contribute, ui.view.contribute, ui.view.input, workspace.read, pane.read_metadata, pane.read_screen, pane.create, pane.close, pane.send_input, workspace.create, workspace.close, storage.plugin_private, host.events.subscribe. Mutations also need a workspace scope (--workspace PATH, exact path) or --instance.

Contributions:
Context-menu actions with target revalidation after lazy activation, search providers merged into the finder, notifications with severity, prioritized footer status, scoped snapshot subscriptions with sequence gaps and resync, private quota limited key-value storage, activation markers, typed configuration delivered in hello_ack, and plain-text views that either float or dock at the right or bottom edge.

Lifecycle:
Lazy activation, handshake with timeout, concurrent calls with cancellation, generation tagged results so late answers are discarded, approval watcher that revokes live access when a record changes, explicit start, stop, restart, and reload, and descendant cleanup through process groups on Unix and job objects on Windows. Controls are reachable from ctrl+b P, the settings window, the hrdx plugins CLI, and two new control-socket methods, plugins.status and plugins.control.

Where it diverges from the proposal

Plugins are trusted code, not sandboxed code. Grants restrict what a plugin can ask hrdx to do. They cannot stop a same-user executable from reading files, spawning processes, or using the existing control socket. The docs say this plainly instead of implying isolation that does not exist. process.spawn is therefore absent: it would imply control we do not have.

Contributions are declared in the manifest, not registered dynamically during the handshake. That keeps inventory and diagnostics possible without running code and removes a class of registration races.

There is no automatic restart or backoff. A crashed or stopped plugin stays stopped until someone restarts it. Reload is explicit and only accepts a reapproved package at the same path.

Views are host-rendered plain text rows, never raw ANSI and never PTY-backed. Docked views reserve an edge strip outside the split tree rather than becoming tree nodes, so every persistent pane still appears exactly once in the tree and persisted layouts are unchanged.

Plugin-created splits and tabs become ordinary host-owned panes that survive plugin disconnect. Floats created by a plugin are temporary and close with the connection.

Pane input from plugins is bounded and ordered behind keyboard input. To make that safe, pane writes now go through a per-pane queue drained by one go routine, so a child that stops reading its PTY can no longer block the update loop. Keyboard input is never dropped.

Grants are per workspace or instance. Per tab and per pane grants are not implemented. Tabs have no durable identity and pane IDs are process local.

Where to look

• README section "Experimental plugins" for the user-facing walkthrough.
• docs/plugin-platform.md for the complete manifest, method, grant, limit, lifecycle, and budget reference.
• examples/plugins/hello for a standard-library-only reference peer with an action, a provider, a config option, and an optional view.
• https://www.hrdx.dev/docs/plugins for the website summary.