Proposal: an extension/plugin contract so large features stop landing in core (and existing ones can migrate out)

[vdmkenny]

Problem

We have a recurring flood of multi-thousand-line feature PRs landing (or trying to land) in core. A non-exhaustive snapshot of what is open right now:

• WhatsApp feat(whatsapp): add Evolution API integration with 4 agent tools + au… #4357 (+1,016)
• Atlas markdown vault feat: Atlas — an Obsidian-style markdown vault with graph, Bases queries, and AI/MCP access #4435 (+3,849)
• Media/ComfyUI feat(media): add local-first media registry with ComfyUI generation routing #4014 (+4,587)
• Docker-MCP gateway feat(mcp): add Docker MCP gateway integration with Windows launcher auto-start #4042 (+2,252)
• OIDC SSO feat(auth): add generic OpenID Connect (OIDC) single sign-on #3508 (+2,990)
• TTS read-aloud feat(tts): add universal read-aloud TTS for AI responses #4009 (+2,369)
• MemMachine memory feat(memory): native MemMachine and TRACE-inspired hierarchical memory engine #3730 (+2,172)
• ICS calendar feat(calendar): add ICS URL subscription and refresh #3759, git-workflow feat(workspace): add git workflow backend APIs #3259, macOS packaging feat(macos): add portable self-contained .app + DMG packaging #3769
• a flotilla of provider PRs: Kagi feat(search): add Kagi as a search provider #3837, Fireworks feat: add support for Fireworks API provider #3279, Perplexity feat(search): add Perplexity Search as a selectable provider #3340, Astraflow feat: add Astraflow provider support (global + China endpoints) #3379, Atlas-Cloud feat: add Atlas Cloud as OpenAI-compatible LLM provider #3582

Each is hard to review, grows the security and maintenance surface, and re-litigates "should this be in Odysseus." #4395 (a VS Code extension) was declined on exactly these grounds.

Two things that change the framing

1. A plugin system is already proposed in feat(plugin-system): thin contract (previously plugin system) - JSON schema, host facade, registry, reference plugin #4241 (~4,900 lines): an odysseus-plugin.json manifest, iframe/CSP-sandboxed JS, optional Python hooks, and a discovery UI. Its stated motivation matches this one. So this is less a greenfield idea than a decision about feat(plugin-system): thin contract (previously plugin system) - JSON schema, host facade, registry, reference plugin #4241.
2. The project already has extension seams: MCP servers (the tool-plugin mechanism, which Atlas already uses), skills (SKILLS_DIR), the integrations/ directory, and the search/LLM provider registries. Much of the pile fits one of these without new core code.

Tension

#4241 is itself a ~4,900-line bespoke in-tree plugin runtime (iframe sandbox plus discovery UI). That is ironic for a "stop big in-tree PRs" goal, and it is a large new security and maintenance surface of its own.

Proposal: agree the direction before adopting a runtime

1. Lean on the seams we already have. Tools become MCP servers (Atlas already does this); behaviours become skills; LLM and search backends use the provider registries; app-adjacent UIs live out-of-tree (as feat: add the Odysseus VS Code extension #4395 will). Most of the pile fits one of these without new core code.
2. Define a thin extension manifest plus out-of-tree distribution (install/enable, declared capabilities and permissions, no core edit required to add one), rather than an in-tree iframe runtime and discovery UI we maintain forever.
3. Evaluate feat(plugin-system): thin contract (previously plugin system) - JSON schema, host facade, registry, reference plugin #4241 against that bar. Keep the parts that are the keeper (the manifest, the permission model); question the parts that are themselves the surface we are trying to avoid (the bespoke sandbox, the in-tree discovery UI).
4. Write contributor guidance: a new integration / provider / large feature should be a plugin or an MCP server or out-of-tree, not a core PR, so maintainers can redirect these consistently.
5. Mid and long-term migration. The contract is not only a gate for new work, it is a path to slim the existing core. Once the seam is stable, extract current in-tree integrations to plugins / MCP servers incrementally, easiest-first: the provider registries are already plugin-shaped; then app-adjacent features (TTS, media, calendar ICS, eventually email/cookbook) move out behind the same contract, each as its own small migration PR with a compatibility shim so nothing breaks for users. Target end state: a lean core (chat/agent loop, auth, the extension host) with everything else a plugin.

Goal

New features ship as plugins / MCP servers / out-of-tree, and the core gets lighter over time as existing integrations migrate out.

cc @pewdiepie-archdaemon @lalalune @NicholaiVogel @Michiel-VandeVelde @Bandonker @mikaelaldy @vcscsvcscs @alteixeira20 @nopoz @crazyjackel @RaresKeY @Zen0-99 (author of #4241) because this overlaps the Stabilization v1 milestone (#3163) and maintainer-owned direction.

[Zen0-99]

Thanks for the thoughtful framing @vdmkenny - you've made good points on where the value is and where I over-engineered.

On the UI: I'd love to keep the discovery UI if the maintainers are open to it. My bias is toward making complex things feel simple, and I've seen too many plugin systems die because editing a JSON file and restarting a server is the onboarding flow. A visual grid with install/enable toggles turns that into one click. I'm happy to split it into a follow-up PR if it makes review easier, but I'd prefer not to lose it entirely.

On the iframe sandbox: Hindsight is 20/20, and you're absolutely right here. The sandbox was a premature "what if plugins are evil" hedge. But Odysseus plugins are server-side, pip-installed packages - same trust model as any other Python dependency. We already gate capabilities through the manifest and permission model, so the bespoke sandbox and custom JS↔Python bridge are just dead weight. Dropping them cuts ~2,500 lines and removes a fragile security surface I don't think we need.

Revised plan, taking both points on board:

Keep: manifest, permissions, discovery UI, simple entry-point loader
Drop: iframe CSP sandbox, custom JS↔Python IPC bridge
Target: ~2,500 lines instead of 4,900
I'll reshape #4241 to this scope. Happy to split the UI into its own PR if that helps review - whatever gets the contract part landed first and fast will ease the load on all the collaborators

[vdmkenny]

I think the discovery UI has some UX value to evaluate separately, but we should keep the first implementation of this as thin as possible.

[erikLundstedt]

I have a simple request on the "keep the UI" part,
make the UI edit a json(or anything else that isn't yaml or indentation dependent) file, this way I can add that file to a separate git repo(my config/dotfiles for example) and even generate it myself(I write a lot of code that simply writes to a config file, and something like json is easy enough to generate from most languages, or to edit with a json-tree-editor(online ones, and offline ones))

rant involving large projects moving config behind fancy UI, while making it hard to backup or sync

My issue is when projects decide to make great-looking UI's that change data in some database, hidden(as in hard to find, or obfuscated, I don't count $HOME/.config, as that is still easy to find/navigate) or binary-file, home-assistant is one example of this, the integration-config/settings are stored in one huge json file that is largely hidden from the user(in a directory not shown by default), and "hard" to edit by hand(everyting on a single line if I recall), their excuse is to "just use the fancy UI", but that is not always possible(like changing the IP of an already added device)

home assistant is a particularly bad case, as they used to store that config in the main user config.yaml file, but now classify any integrations where you can still do that as "bad" or "outdated", and this is a large, open-source, knowledgable-user-prefered project

[RaresKeY]

I think there are two different problems getting mixed together here, and they need different answers.

If the main problem is PR volume and review pressure, I would rather explore the #4415 direction first: parent trackers, child issues, and PRs as candidate implementations. That gives maintainers a way to route broad or overlapping work without turning every useful feature into an extension-platform decision. A PR can be valid, partial, superseded, or not good enough, while the underlying issue still stays owned somewhere.

If the goal is broader than review routing, and we want to deliberately slim core over time by pushing feature ownership out to independent maintainers, then I think that needs an explicit direction call from @pewdiepie-archdaemon. That is not just a technical implementation detail. It changes what Odysseus is responsible for owning.

My bias is still toward core-owned paths or standalone integrations for important capabilities, mainly for security, maintainability, style preservation, and product cohesion. The macOS comparison that comes to mind is not “everything is extensible”; it is that the owned paths feel coherent and generally work together. Odysseus probably needs some of that discipline too.

I am not totally opposed to plugins. I just do not think “large feature” automatically means “should be a plugin.” I would expect core to keep owning some foundational product capabilities. The line is probably not “small in core, large out of core.” It is more like: core owns the product contract and essential service boundaries; extensions add optional or specialized behavior around those boundaries.

Right now I think core still needs more scaffolding before a plugin platform is the right pressure valve. The architecture Odysseus canonizes becomes the shape plugins build against, and that directly dictates how useful, stable, and maintainable those plugins can be. If the plugin API is built around unsettled internals, plugins either become fragile wrappers around today’s implementation details, or core gets stuck preserving accidental contracts too early. In particular, the inference path is likely the most important service boundary to canonize first: Odysseus already has multiple engine/provider shapes, and plugins should build on stable internal contracts and core adapters for the essential flows.

Looking at #4241 specifically, my concern is not just size. It makes Odysseus own a lot at once:

• remote plugin discovery and install behavior;
• iframe UI hosting;
• a postMessage bridge;
• manifest permissions;
• backend Python hooks;
• settings persistence;
• file-hash verification;
• docs and expectations around safety.

That is a full extension platform surface. The iframe/backend split also needs a much stronger threat model before I would be comfortable treating it as safe. Browser-side, iframe sandboxing and message bridges need to be designed as hard security boundaries, not just implementation details. Backend-side, a Python subprocess is still host code unless there is real OS/process/container isolation. It may be a cleaner execution model than in-process imports, but it is not a security boundary by itself.

The ComfyUI extension-manager path is a useful warning here. Once extensions become common, extensions ask for more permissions, users get trained to grant those permissions because otherwise things do not work, and the host project inherits pressure to support and secure that ecosystem. ComfyUI has had to add explicit controls around things like arbitrary git URL installs and pip installs. I would rather Odysseus not accidentally normalize “random repo code with broad permissions” as something the project implicitly owns.

So my current position would be:

• use Issue buckets: parent trackers, child issues, and PR candidates #4415-style tracking first if the immediate problem is PR/review volume;
• keep core-owned paths for foundational and product-cohesive capabilities;
• use existing seams where they already fit: MCP servers, skills, provider adapters, and scoped external integrations;
• if plugins are accepted, make the trust boundary explicit: install at your own risk unless/until Odysseus has real permission enforcement, provenance, review, update, and sandboxing models;
• treat feat(plugin-system): thin contract (previously plugin system) - JSON schema, host facade, registry, reference plugin #4241 as useful design input, but not something I would merge as the plugin architecture yet.

A thinner next step might be contributor guidance plus a manifest/capability discussion, without adopting a runtime/discovery UI immediately. That would let maintainers redirect broad work more consistently while leaving the bigger question open: whether Odysseus wants to own a plugin platform, or just define stable external seams around a coherent core.

The main thing I would want to avoid is exposing Odysseus as a platform before the core shape is ready, because once people build plugins against it, today’s internal structure starts becoming tomorrow’s compatibility contract.

[RaresKeY]

@vdmkenny I’d like your view on my last concern: exposing Odysseus as a plugin platform before the core service boundaries are stable.

That is the main risk I’m worried about. Once people build against a plugin API, today’s internals can turn into tomorrow’s compatibility contract. Do you think the thin contract can move in parallel without freezing those internals too early, or should it wait until the core boundaries are clearer?

[vdmkenny]

@RaresKeY Agreed on the risk, and I think it can move in parallel as long as we do not open to external plugins yet.

The freezing only bites once outside parties build against it. While we are the only consumer, the contract is an internal API: change a seam, fix every call site in the same PR. So: contract now, dogfood now, external plugins later once the boundaries are clear.

Dogfooding means migrating a few in-tree features behind the contract while they stay in the repo. They are the health check for the seam: if a real feature cannot sit behind it cleanly, it is not ready, and we learn that with zero external exposure. Pick ones that each exercise a different facade:

• a tool feature for host.add_tool (image generation), which is why I want the tool_implementations to registry refactor (refactor(tools): split tool_implementations and part of ai_interaction.py into many new tools files within src/agent_tools #3629) done first, so the tool seam sits on the settled registry not the elif dispatch we are mid-removing;
• a routes plus settings plus UI feature for add_router / add_settings_section and the frontend registry (calendar ICS, TTS, gallery);
• a provider for register_provider, since the provider registries are already close.

And keep the contract agnostic of internals: host.* should wrap seams we will keep (include_router plus require_admin, the provider registry, settings), not hand plugins our implementation. That plus a readiness pass on those boundaries is what lets internals evolve underneath without breaking dogfooded plugins.

So thin contract plus in-tree dogfooding can run in parallel and actually de-risk the boundaries. Opening externally is the step that waits.

[RaresKeY]

That makes sense if “contract now” means internal dogfood only. If we can still change every consumer in the same PR, the compatibility-freeze risk is much lower.

The part I am still unsure about is why that needs to become an explicit plugin-shaped contract first, rather than canonizing the compatibility layers one by one. If the durable surface is host.add_tool, host.register_provider, host.add_router, host.add_settings_section, and a frontend registry, then those adapter seams seem like the things to settle first. A plugin manifest/entrypoint can wrap them later once they are real contracts.

That distinction matters because the current thin shape still looks externally consumable: Python entry-point discovery, odysseus_compat, schema, and “writing a plugin” docs all start to look like a public compatibility target. If the policy is “dogfood now, external plugins later,” I would keep the first slice framed as internal extension seams/adapters, not a plugin platform yet.

For external plugins, the extra value is clear: distribution, ownership boundary, enable/disable, declared capabilities, and install-at-your-own-risk transparency. But if external plugins wait, the near-term value of the plugin layer seems narrower: dogfooding and organizing in-tree optional features.

That may still be useful, but I think the speed gain has to come from settling the adapters faster. Otherwise the plugin contract risks becoming a second abstraction over unsettled internals. I would rather see core say “we are defining the adapter shape you can hook into later” than expose Odysseus as a plugin platform before those adapter shapes are ready.

[vdmkenny]

@RaresKeY You're right about the host contracts. I do think that we should keep the plugin effort alive, and a branch tracking dev, so it can go in when everything's ready. I don't want to rush this, but I do feel it's an important feature to keep in the works. I don't want to kick it out the door only to have it limit what we can do internally.

[vdmkenny]

Just as an experiment, I created a hello-world plugin that exercises some of the capabilities present, and documents the gaps where I had to use a workaround because there was no host contract function for it: https://github.com/vdmkenny/odysseus-hello-world-demo

[vdmkenny]

Thanks @Zen0-99, the revised scope sounds right. Here's how I'd suggest we shape it.

I'd propose landing the contract first as one small PR, with a reviewable core of roughly:

• an odysseus-plugin.json manifest: name, version, entry_point, odysseus_compat (version range), description, author, homepage/repository (so it links back to source), license, and capabilities;
• a bundled odysseus-plugin.schema.json (JSON Schema), validated fail-closed at load so a non-conforming manifest is rejected with a clear error rather than half-loaded (plugins could add "$schema": "..." for IDE autocomplete and their own CI lint);
• discovery via Python entry-points (an odysseus.plugins group) so plugins are pip-installed and out-of-tree, which is the main "keep core light" lever, with a local plugins/ dir for dev;
• a register(host) hook and a host facade over the seams we already have: host.add_router(router, admin=False) (wrapping app.include_router plus require_admin), host.add_static(...), host.register_provider(...), host.add_settings_section(...), host.add_tool(...);
• enable/disable persisted, plus a minimal reference plugin, tests, and a short "writing a plugin" doc.

One thing worth flagging: the frontend would need a genuinely new extension point. Today nav entries and settings tabs are hardcoded in index.html, so for any plugin to surface UI, core would need a small registry that renders plugin-contributed nav items / panels / settings tabs and lazy-loads their frontend modules. That seems like the load-bearing piece, so it probably belongs in the contract PR even though no UI ships with it yet.

On capabilities, I'd suggest tiering them: ordinary (tools, routes, ui, settings, provider) versus privileged (for example manage_plugins to toggle other plugins, or mounting admin routes). It would make sense for privileged ones to require explicit operator opt-in and to be flagged loudly in the UI, since a plugin asking for manage_plugins could disable a security plugin.

It would also be worth being explicit about the trust model in the docs. Since plugins are pip-installed server-side Python (the same trust as any dependency), the manifest is really transparency rather than a sandbox: author, the source link, and the declared capabilities (especially privileged ones) surface so an operator can make an informed install decision. I'd suggest saying plainly that it does not isolate a hostile plugin, which is also why I agree dropping the iframe sandbox is the right call.

For the discovery/management UI, my suggestion would be a follow-up PR that ships it as the first bundled plugin (default-enabled, removable). That would dogfood the contract end to end (if our own UI cannot be a plugin, the seam is not expressive enough), and it would naturally be the holder of the manage_plugins privileged capability and the canonical reference example.

It might also help to draw the plugin vs MCP vs skill line so contributors and maintainers can redirect consistently: an MCP server for an external tool-only process (WhatsApp's tools could fit there), a plugin for in-process Python that adds routes/settings/providers/UI (Atlas-shaped), and a skill for prompt/behaviour only.

Over the mid to long term, existing features could then migrate out behind the same seam, easiest-first: the provider registries are already plugin-shaped, then app-adjacent features (TTS, media, calendar ICS, eventually email/cookbook), each as a small PR with a compatibility shim so nothing breaks for users.

Net, the idea would be: a small contract PR (seam + schema + a tiny example) first, the discovery UI as the first bundled plugin right after, and core getting lighter as features migrate behind the same contract. Curious what you and the maintainers think, especially on the frontend extension point and the privileged-capability tier.

[CoolJohn-lab]

Seems like a lot of work to go to rather than just telling people no, we’re not adding perplexity search.

[CoolJohn-lab]

Yeah... an endless list of "useful" plugins just like obsidian, and cursor, and Claude code, and ollama, and chrome, and like virtually every app ever. yawn

Does anyone actually care about plugins other than plugin authors? Or people who are just obsessed over one particular niche, flavour of the month product?

Perplexity is a great example, a flash in the pan fad that is now struggling to retain users and stay relevant, now that Google just does what it does, but better.

If you want to trend every app towards the same boring mess of abandoned plugins and long scrolling lists of crap that was once popular and now is just a joke, sure, force plugin support into Odysseus.

The reason I came to Odysseus was precisely because it was not a "build it yourself with plugins" type experience that every other god damn app in the world is, it had curated, first-party features.

But that's just me I guess. Do whatever you want, I can't stop you.

[Zen0-99]

@CoolJohn-lab From my experience Odysseus was made from "Uu I like this thing, oh and this, and this" - PewDiePie's built himself and others a platform/workspace and to expect everyone to like and use it in the same way. Just like people like different pens/pencils/paper on a physical workspace, this being a digital workspace lacks the ability to fit custom wants/needs. A plugin feature can exist without you ever interacting it, if it's working great for you know then all the power to you

[wolfgangDGS]

I understand what you're saying.
A lot of flavour of the month plugins can get deprecated quick, only serve a couple of people or even be a an unsafe mess.

But I also don't think the other guys meant stripping down Odysseus to barbones either, right? At least that's what I'm understanding from what the others are discussing.

You'll still have a good and reliable final product with the mainstream and important features, reducing maintenance work, while still allowing people to customize it.

Or maybe I'm misinterpreting something the others said

[CoolJohn-lab]

they want to move even existing features to be plugins...

[Zen0-99]

I think there is a misunderstanding. The idea is to allow existing PRs to become plugins rather than core code components. Everything that exists now, stays as is - non-plugin based.

[holden093]

I have been following this and wanted to add something grounded rather than theoretical, since my OIDC PR (#3508) was one of the examples in the opening post.

I actually tried porting OIDC to the contract

Spent a day mapping it out. Of the 11 integration points OIDC requires, 5 map cleanly to the contract (routes, settings UI, static files, env reading, state management). The other 6 have no API — and they are the core auth ones: calling AuthManager methods, exempting routes from auth middleware, patching password/2FA rejection into existing routes. Making this work would require building a plugin auth SPI as large as OIDC itself before the port could start.

I do not think this is a flaw in the contract. It is evidence the contract has the right scope. Auth is the one subsystem where a bug breaks the entire trust boundary — it should stay in-tree with mandatory multi-reviewer scrutiny. A plugin contract that says "yes" to messaging and "no" to auth is correctly bounded.

Messaging integrations are the proof case

The same analysis applied to the WhatsApp PR (#4357) tells a completely different story:

What WhatsApp needs	Contract support
Webhook receiver routes	host.add_router() ✅
API key / webhook secret config	host.add_settings_section() + odysseus.set_setting() ✅
Send/receive message tools	host.add_tool() ✅
Sidebar panel / chat UI	registerSidebarItem + frontend injection ✅
Static assets (icons, CSS)	host.add_static() ✅

Every seam exists. And the blast radius is self-contained — a bug in Telegram breaks Telegram, not login. Discord, Matrix, Signal follow the same pattern. The contract already covers the entire messaging integration category without a single new API.

Provider PRs are the easiest win

The provider long tail (Kagi #3837, Fireworks #3279, Perplexity #3340, Astraflow #3379, Atlas-Cloud #3582) is the most mechanical, repetitive review burden. All five follow the same pattern: add a class, register it. Once register_provider is wired to the dispatcher — which @vdmkenny already flagged as the missing piece — this entire class of PRs evaporates. That is 5+ PRs worth of maintainer load eliminated by wiring one seam. Hard to find better ROI.

@vdmkenny already called it

I want somebody to use this with whatever niche provider or integration they want to, just like you can with an IDE. I just do not want to make maintaining that for the next 10 years our concern. That is why plugin systems exist.

That is the direction. The question is not whether — it is how thin and how soon.

Concrete dogfood candidate: calendar ICS

@vdmkenny suggested dogfooding internally first. Calendar ICS (#3759) is the ideal first target: it needs a route (iCal fetch/webhook), settings (calendar URL, refresh interval), a sidebar item, and tools (create event, list events). Every one maps to the contract. It touches 4 different host APIs, the existing code is already in-tree to diff against, and it is small enough to port in a day. If the calendar cannot sit cleanly behind the contract, we learn that before external plugins touch it — if it can, we have proof the contract works.

---

Bottom line: the contract has the right scope. Auth stays in-tree. Messaging and providers move behind it. Let us land the thin version in #4241, wire add_tool / register_provider to the dispatcher, dogfood with ICS, then open the gates for WhatsApp/Telegram/Discord. Happy to help with the messaging seams — I now know the contract well enough to say exactly what fits and what does not.

[vdmkenny]

Thanks for the endorsement and analysis. I think there's some gap-analysis to do on the current provider contract before we can formalize it. I think we should finish https://github.com/pewdiepie-archdaemon/odysseus/issues/3629 so the tooling is centralized and we can hook the register tool end on it first. We'll probably learn this by maintaining #4241 out of dev and testing some proof of concept plugins against it (providers, existing functions) until we can be reasonably sure and publish a beta contract.

[vdmkenny]

You're welcome to port your feature PRs to it as a test, though I think the OIDC one is a bit ambitious for the reasons you called.

[holden093]

OIDC could be out of scope, but I can try to port the WhatsApp integration PR as a proof of concept.
Even if it lives and then dies on my machine, it could help us identify any potential issues and/or caveats

[WGlynn]

@holden093's port attempt is the most useful thing here, and it quietly settles the #4241-vs-contract question. The 6 of 11 points with no API aren't an OIDC quirk, they're the measurement: a plugin contract reaches only as far as the core already exposes a seam, and the valuable features are exactly the ones that need the unexposed core hooks. So the manifest isn't the hard part, and neither is the runtime. The hard part is deciding which core capabilities become stable, supported seams.

That argues for sequencing it backwards from the usual: let real port attempts enumerate the missing seams, expose those few as versioned core APIs, then let the contract bind against them. We hit the same thing defining a messaging hub as an interface first and porting components to it. The ones that needed several unexposed internals told us the interface was incomplete, not that the feature was wrong.

[alteixeira20]

I want to be clear that I fully agree with the need for a plugin-based system in Odysseus.

I think it is the right long-term direction. The current pattern of large, niche, or optional feature PRs landing directly in core is not sustainable. It increases review pressure, expands the maintenance and security surface, and makes future refactors harder. A plugin system gives those features a proper home without making the core team responsible for maintaining every integration indefinitely.

That said, I think the important question is sequencing.

I would separate plugin-based direction from public plugin-platform exposure. We can agree that Odysseus needs plugins without immediately exposing a broad third-party API before the core seams are stable.

The concrete port attempts are the most useful signal here. OIDC not fitting cleanly is probably evidence that auth should stay core-owned and receive heavier review, not evidence that the plugin direction is wrong. Messaging integrations, providers, calendar-style integrations, and app-adjacent optional features seem like much better proof cases because their blast radius is smaller and they map more naturally to extension seams.

So my preferred path would be:

1. Commit to plugins as the long-term direction for optional and niche integrations.
2. Define the internal host seams first: add_tool, register_provider, add_router, add_settings_section, frontend registry, and any other seams real ports prove are needed.
3. Dogfood those seams with in-tree migrations before opening them as a public external plugin API.
4. Keep auth and other trust-boundary features in core unless there is an explicit maintainer decision to design a dedicated SPI for them.
5. Once the dogfooded seams are stable, wrap them in the manifest/entrypoint/distribution model and make that the public plugin contract.

This still moves the plugin system forward, but avoids freezing unsettled internals too early. I would like to see the first milestone framed as something like “stable internal extension seams with dogfood ports,” followed by the public plugin contract once those seams have proved themselves.

I also think the review-pressure problem should stay separate. Parent trackers, clearer roadmap buckets, and stronger PR routing help regardless of plugins. But for the long-term health of the project, I do think Odysseus needs a plugin-based architecture so optional integrations can live outside core ownership instead of becoming permanent maintenance drag.

[holden093]

@vdmkenny @RaresKeY @Zen0-99 — I've been dogfooding the plugin contract from #4241 by building a real GitHub integration plugin on top of feat/plugin-system. The full source is at holden093/odysseus — feat/github-plugin.

First, a thank you — this was genuinely the most informative experiment I've run as a sysadmin. Even though the implementation was AI-driven, understanding how a plugin contract maps to real infrastructure (git state machines, fork sync flows, rebase/merge orchestration) taught me a lot about the boundaries Odysseus draws between core and extension. The challenge of making a plugin feel native without touching core gave me a real appreciation for the design work in #4241.

The plugin evolved through four phases — started as simple branch listing, ended as a full conflict resolution center with AI integration. Plugin code is ~1,700 lines, fully self-contained in plugins/github/. Each phase exercised a different part of the contract and each delivered.

AI-driven development: I'm not a frontend developer. Every line was produced by an agent reading the plugin contract. The surface is small enough that an LLM can build a real, multi-featured plugin end-to-end — that's the strongest signal I can offer that the API is learnable.

Core wiring: the plugin itself needed zero core changes. Marginal fixes to the plugin host from #4241 (~50 lines across tool_execution.py, agent_loop.py, settings.js) were needed for dispatch and prompt injection. I'd like to contribute them back — PR against Zen0-99's fork, or wait for upstream?

Documentation gap: since feat/plugin-system isn't in-tree, there's no canonical place to point plugin authors. If the contract lands, a docs/plugins/ reference would unblock the next person.

---

Technical summary

Phase 1 — Backend: server-side POST /merge-profile and POST /rebase-profile replaced fragile frontend loops. GET /info exposes git state with conflicting_files. Recovery endpoints for merge/rebase abort/continue. Git identity isolated via _git_env() — no host container changes.

Phase 2 — Frontend UX: native dialogs replaced with Promise-based custom modals styled to the dark theme. _busy flag prevents double-submit.

Phase 3 — Persistence & Sync: POST /sync rewritten to checkout → fetch upstream → merge → push to origin. Defensive migration prevents data loss on rebuilds.

Phase 4 — Conflict Resolution Center: three-pane modal with theme-safe colorized diff editor, LLM chat using native agent tool execution (file path only, agent reads/writes via its own tools), "Apply Fix" safety net, auto-continue chain on completion.

[CoolJohn-lab]

if your 12B model can't use an MCP or a skill it definitely can't use an MCP or a skill behind a plugin layer.

[RaresKeY]

@CoolJohn-lab I think you are right for the agent-only case: if the goal is just “let an agent call GitHub/WhatsApp/etc.”, then MCP plus a skill can be enough. The deterministic code still exists; MCP is one typed tool/API surface the harness can call. Odysseus also already has generic API integration surfaces in that same general category.

But Holden’s GitHub experiment is useful because it shows a different layer. Raw API calls are tool territory. A native Odysseus workflow with routes, settings, UI panels, persistence, webhooks, conflict handling, and deterministic orchestration is plugin/host-extension territory.

So I do not see this as MCP vs plugins. MCP gives agents deterministic tools. A plugin contract would give Odysseus deterministic extension points. A good plugin can still expose tools/MCP/skills internally where that is the right shape.

That is also why I think the priority is core adapter/host seams first: add_tool, register_provider, add_router, add_settings_section, frontend registry, etc. Real ports like GitHub, WhatsApp, ICS, or providers are useful because they measure which seams are actually stable before the manifest/distribution layer becomes a public contract.

[Plaer1]

@holden093
How's this coming along; I have a bunch of features I would like to start porting to your plugins system if you're ready for anyone else to much on ur dogfood yet.

[holden093]

@holden093 How's this coming along; I have a bunch of features I would like to start porting to your plugins system if you're ready for anyone else to much on ur dogfood yet.

@Plaer1 — quick clarification: the plugin system isn't mine — it's Zen0-99's work in #4241 (feat/plugin-system). I was just dogfooding the contract by building a real GitHub integration plugin on top of it to see how it holds up.

That said, as a consumer of it: the surface is small enough that an LLM can build a full plugin end-to-end, which is the strongest signal I can offer that the API is learnable. If you want to try building on top of feat/plugin-system now, the GitHub plugin source is a working reference — but be warned it's not in-tree yet, so there's no canonical docs and the host needed ~50 lines of marginal fixes for dispatch/prompt injection.

For the question of when it's "ready for others" — that's really a question for @Zen0-99 and the maintainer discussion happening in this thread about whether #4241 lands as-is or gets reshaped into the thinner contract @vdmkenny proposed.

[Plaer1]

@holden093 first and foremost; tysm for the fast reply + clarification boss. I read the whole thread and was unable to parse if he had written a spec that you implemented or visa versa.
and i don't mind if it's hard to understand or in a flexible state right now honestly; if it's the strongest contender for a plugin framework I'll work with it as-is and update my code as they go, otherwise i couldn't really construe my participation in the community as very good faith imo (if i wanted stability or control i would build something myself, my way, but that's just not my approach usually lol).
thanks again for all the info; I'll go look at #4241 and see what I have if anything can be built off of it.

[eyeofastarte]

Hi @vdmkenny and everyone,

Solid proposal, the flood of huge PRs is exactly the kind of coordination pain I was talking about in #5092. I appreciate you laying out the plugin angle and calling out the irony with #4241 being so big itself.

I agree we need to handle scope better, but I'm not convinced pushing large features out via plugins is the main answer. In a fast-moving project like this, some overlap and one PR stepping on another feels pretty normal. It's the energy that comes with lots of people building stuff. The real bottleneck I'm seeing is prioritization: we get a bunch of small fixes daily while bigger direction decisions drag, and everything ends up competing.

What would help most is clearer ways for the community to rank and choose priorities (a simple feature page or voting system on key items). That would give maintainers better signals and let us focus without trying to do everything at once. Accepting that picking X might mean reworking Y later seems necessary too.

On the governance side, as we scale it might be worth thinking about some lightweight bylaws or a more structured way for input (maybe something collaborative that fits the project's vibe). Direct community ranking on features feels like it could cut through a lot of the current friction.

Happy to help flesh out a basic voting idea or pull together some priority examples (search quality keeps coming up for me).

[MADPANDA3D]

Dogfood evidence: four small in-tree host seams from a maintained Voice Orb fork

We have now published a maintained-fork beta that dogfoods voice, bounded foreground actions, read-only Calendar context, and user-initiated camera/media lifecycle behavior against canonical dev at c80462e4621c1a3360e5441843bb83b4691a8766.

This is not a request to merge the fork delta or to call the current extension work a stable plugin ABI. The fork's compatibility record deliberately keeps plugin_abi: null. Dogfooding instead exposed four smaller, independently reviewable core seams:

1. An enumerated foreground-action registry with strict payload schemas and no selector/script/URL escape hatch.
2. A bounded, versioned client-state snapshot for named logical views, never raw DOM or document content.
3. An owner-scoped, read-only Calendar facade with result limits and freshness/error metadata.
4. Documented voice/static lifecycle hooks for app-owned mounting, interruption, stream completion, teardown, and same-origin assets.

Public evidence:

• v0.3.0-beta.1 prerelease
• Sanitized reproducible demo protocol and release results
• Threat model, privacy lifecycle, compatibility evidence, and proposed seam boundaries

The product setup UI, worker adapters, and explicit Tailnet model discovery remain maintained-fork concerns; they are not part of this upstream ask.

Would maintainers like these as independent PRs against dev, starting with the foreground-action registry and migration of the existing Calendar/document actions, or would you prefer a narrower precursor first?