90 lines
5.8 KiB
Markdown
90 lines
5.8 KiB
Markdown
---
|
|
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-06-03T12:25:05Z
|
|
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.
|
|
- `work-items/open/20260603-122317-plugin-feature-contribution-registry/` — implementation-oriented runtime registry split-out for built-in and external feature contributions.
|
|
- `work-items/open/20260603-122317-hook-public-surface-hardening/` — prerequisite hardening for public Hook contribution safety.
|
|
- 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**
|
|
- Detailed implementation is split to `plugin-feature-contribution-registry` so this ticket can stay focused on the architecture surface and invariants.
|
|
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.
|