diff --git a/work-items/open/20260531-010005-plugin-extension-surface/artifacts/.gitkeep b/work-items/open/20260531-010005-plugin-extension-surface/artifacts/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/work-items/open/20260531-010005-plugin-extension-surface/item.md b/work-items/open/20260531-010005-plugin-extension-surface/item.md new file mode 100644 index 00000000..5789803a --- /dev/null +++ b/work-items/open/20260531-010005-plugin-extension-surface/item.md @@ -0,0 +1,87 @@ +--- +id: 20260531-010005-plugin-extension-surface +slug: plugin-extension-surface +title: Plugin: define extension surface for hooks and tools +status: open +kind: feature +priority: P2 +labels: [plugin, hooks, tools, wasm, mcp] +created_at: 2026-05-31T01:00:05Z +updated_at: 2026-05-31T01:01:09Z +assignee: null +legacy_ticket: null +--- + +## Background + +insomnia currently has internal Hook / Tool concepts, plus a separate planned MCP integration ticket (`mcp-integration`). The next design step is to define the project-level Plugin surface: how user/project-provided extensions can contribute Tools and Hooks without weakening scope, permission, history, or prompt-context invariants. + +The plugin surface should not be a grab bag of arbitrary code execution. Candidate extension mechanisms have different trust and protocol properties: + +- MCP: protocol-bound external tool/resource/prompt provider surface. +- TOML/config-only hooks: declarative configuration for simple hook behavior without arbitrary code. +- WASM: planned first programmable plugin runtime for Hooks and Tools, with explicit capability imports and sandboxing. +- General scripting languages: considered, but not the initial direction because arbitrary script execution broadens the trust/runtime surface too quickly. + +## Related work + +- `work-items/open/20260529-161928-mcp-integration/` — MCP integration as one plugin backend / external capability bridge. +- Existing internal hooks/tools code: `crates/pod`, `crates/tools`, `crates/llm-worker`. +- Manifest permission policy and scope enforcement must remain authoritative for plugin-provided tools. + +## Requirements + +- Define a Plugin surface that can provide: + - Tools callable by the LLM through the normal ToolRegistry / permission / scope path; + - Hooks observing or influencing Pod/Worker lifecycle through the existing Hook boundary, not by directly mutating worker history/context. +- Separate plugin description/registration from plugin runtime implementation. + - A plugin manifest should declare provided tools/hooks, required capabilities, configuration schema or config values, and trust/runtime type. + - Runtime implementations can include MCP, declarative config hooks, and WASM in separate phases. +- Keep MCP as a related backend, not the whole plugin model. + - MCP servers remain untrusted external capability providers bridged through allowlists, bounded output, scope/permission policy, and explicit resource/prompt use. +- Define a declarative hook path for simple TOML/config-only behavior where code execution is unnecessary. +- Define a WASM plugin direction for programmable Hooks/Tools. + - WASM modules must receive explicit host imports/capabilities only. + - File/network/process access must not be ambient; all external effects go through host-provided capability APIs and existing policy checks. + - Tool outputs must be bounded and recorded through normal history/tool-result paths. +- Preserve LLM context/history invariants. + - Plugins must not inject cross-turn invisible context. + - If plugin output becomes model-visible, it must enter through durable history/tool/hook paths according to existing rules. +- Preserve scope and permission invariants. + - Plugin-provided tools must not bypass `ScopedFs`, manifest tool permission policy, child scope delegation, or web/network policy. +- Clarify trust model and lifecycle. + - Builtin vs project vs user plugins. + - Discovery/enablement through manifest/profile/config. + - Versioning / compatibility boundaries. + - Diagnostics when a plugin cannot load or asks for unavailable capabilities. + +## Non-goals + +- Implementing the full WASM runtime in the first design step. +- Implementing MCP itself beyond referencing the existing MCP integration ticket. +- Supporting arbitrary host scripting languages as a first-class plugin runtime. +- Allowing plugins to mutate session history, memory, prompt context, or scope outside approved APIs. +- Adding UI plugin systems or TUI rendering extensions. + +## Suggested phases + +1. **Design / architecture note** + - Define Plugin, PluginManifest, PluginRuntimeKind, Tool contribution, Hook contribution, capability request, and trust/source model. + - Map MCP, declarative hooks, and WASM onto that model. +2. **Internal registry boundary** + - Introduce code structure that can register plugin-provided tool/hook descriptors without changing runtime behavior yet. +3. **Declarative hooks MVP** + - Add a non-code configuration path for simple hook behavior if an immediate use case exists. +4. **WASM spike** + - Evaluate runtime (`wasmtime` or alternative), host imports, resource limits, serialization, and Nix/package impact. +5. **MCP bridge alignment** + - Ensure `mcp-integration` plugs into the same Tool/permission/output boundary rather than becoming a parallel extension path. + +## Acceptance criteria + +- The repository has a documented plugin architecture proposal covering Tools, Hooks, runtimes, capability model, trust model, and discovery/enablement. +- MCP is positioned as one plugin backend / bridge and linked to `mcp-integration`, not treated as the only extension mechanism. +- The proposal explicitly explains why arbitrary scripting languages are deferred and why WASM is the initial programmable runtime direction. +- The design preserves existing scope, permission, history, and prompt-context invariants. +- Follow-up implementation tickets can be cut independently for declarative hooks, WASM runtime, and MCP bridge integration. +- Any code changes in this ticket, if taken beyond design docs, are limited to safe internal boundaries and have focused tests. diff --git a/work-items/open/20260531-010005-plugin-extension-surface/thread.md b/work-items/open/20260531-010005-plugin-extension-surface/thread.md new file mode 100644 index 00000000..e2a886a2 --- /dev/null +++ b/work-items/open/20260531-010005-plugin-extension-surface/thread.md @@ -0,0 +1,24 @@ + + +## Created + +Created by tickets.sh create. + +--- + + + +## Decision + +Initial decision note from user discussion: + +- The plugin surface should mainly expose Hooks and Tools. +- MCP is related, but should be treated as one protocol-bound backend/bridge rather than the entire plugin model. +- Planned plugin mechanisms: + - MCP for protocol-constrained external capability providers; + - TOML/config-only hooks for simple behavior that does not need arbitrary code; + - WASM for programmable Hooks/Tools with explicit host capabilities. +- General scripting languages were considered, but the initial direction is WASM because it offers a clearer sandbox/capability boundary. + + +---