feat: Integration ecosystem refactor — monorepo, shared core, multi-account

[ruttydm]

Summary

Fundamental restructuring of how integrations are organized, shared, and loaded. Four commits that extract shared logic into a new integration-core package, decompose the monolithic ToolRegistry into 15 provider classes, consolidate 13 integration packages into a sibling monorepo, and add multi-account support.

99 files changed, +20,111 / -5,965 lines.

---

Commits

1. 4cffd75 — Integration package ecosystem overhaul (Mar 30)

The big refactor. 28 files, ~5300 lines changed.

• ToolRegistry decomposed — 1965-line ToolRegistry split into 15 BuiltInToolProvider classes under app/Agents/Tools/Providers/. Each registers a named group of tools (agents, automations, calendar, chat, docs, files, lists, lua, memory, svg, system, tables, tasks, workspace).
• New integration-core package — Framework-agnostic contracts (Tool, ToolProvider, CredentialResolver, ConfigurableIntegration) extracted into shared package. Provides ToolProviderRegistry, LuaCatalogBuilder, LuaDocRenderer, LuaBridge.
• Dual dispatch — LuaBridge handles both new IntegrationCore\Contracts\Tool and legacy Laravel\Ai\Contracts\Tool.
• 13 integration packages migrated — Consolidated from 14 separate repos into monorepo at tmp/integrations/.
• Composer simplified — 28 repo entries → 1 wildcard path + 3 others.
• Code-first architecture — Only DIRECT_TOOL_GROUPS (tasks, system, agents, memory, lua) registered as direct AI tools. Everything else via lua_exec.
• Lua docs added for 6 integrations.

2. 24e2cc8 — Share Lua core via integration-core (Apr 1)

Shared Lua infrastructure extracted from app into integration-core.

• LuaApiDocGenerator — 576 lines of doc generation moved to LuaCatalogBuilder + LuaDocRenderer. App class now thin delegate (~180 lines).
• LuaBridge — Call routing, snake_case→camelCase, positional arg mapping moved to shared class. App wraps with OpenCompanyLuaToolInvoker.
• OpenCompanyLuaToolInvoker — New class implementing LuaToolInvoker contract. Dual dispatch, JSON auto-decoding.
• DynamicProviderResolver — Hardcoded provider URLs/models → ProviderMeta lookups from prism-relay.
• AppServiceProvider — 40+ lines of inline Prism provider registration removed. Now handled by PrismRelayServiceProvider.
• config/integrations.php — Hardcoded URLs → ProviderMeta class constants.

3. df74cb3 — Move integrations monorepo to sibling directory (Apr 5)

Path relocation. tmp/integrations/ → ../integrations/. Updated composer.json, CI workflow, and Claude commands.

4. c4bbbfc — Multi-account integrations, MCP, ecosystem docs, QA plans (Apr 7)

Uncommitted work from the tree.

• Multi-account integrations — account_alias + is_default columns on integration_settings and mcp_servers. Composite unique keys. Expanded IntegrationController with full CRUD for multi-account setups.
• MCP improvements — McpServerRegistrar and McpToolProvider refactored.
• Composer split — Path repos: ../integrations/core + ../integrations/packages/* (replaces single wildcard).
• Ecosystem docs — docs/ecosystem/ with integration docs, iris analysis, kosmokrator audit/research/proposals.
• QA test plans — docs/testing/qa-strategy.md and docs/testing/feature-test-map.md.

---

Key Architectural Changes

Before

ToolRegistry (1965 lines, monolithic)
├── All tools registered inline
├── Hardcoded provider URLs/models
├── Lua doc generation embedded
└── LuaBridge call routing embedded

Integrations: 14 separate repos, cloned individually

After

ToolRegistry (thin coordinator)
├── 15 BuiltInToolProvider classes (one per domain)
├── Integration providers from integration-core
└── Code-first: only 5 groups as direct AI tools

integration-core package (shared)
├── Contracts: Tool, ToolProvider, CredentialResolver
├── LuaCatalogBuilder, LuaDocRenderer
├── LuaBridge (shared call routing)
└── LuaToolInvoker interface

Integrations: single monorepo at ../integrations/
├── core/           (integration-core)
└── packages/       (13 integration packages)

---

Testing Required

Full test plans are in docs/testing/qa-strategy.md and docs/testing/feature-test-map.md. Key areas:

P0 — Must test before merge

• Composer resolution — ../integrations/ sibling exists, composer install succeeds, all packages resolve
• Tool registration — All 15 BuiltInToolProviders register correctly, tools work (both direct and via lua_exec)
• Integration packages — At least one no-auth integration (CoinGecko/Celestial) and one auth-required (ClickUp/Google) return live data
• Multi-account migration — php artisan migrate succeeds, existing settings preserved, new unique keys work
• Custom LLM providers — GLM/Kimi/MiniMax still resolve and generate responses via PrismRelay
• Lua doc generation — lua_read_doc("overview"), lua_read_doc("integrations.clickup"), lua_search_docs(...) all return correct results
• LuaBridge routing — Table args, positional args, dual dispatch (new Tool vs legacy), call logging

P1 — Should test

• Config references — config/integrations.php uses ProviderMeta constants (not hardcoded URLs)
• CI pipeline — Clone step targets ../integrations, composer install succeeds, tests pass
• Tool catalog UI — All namespaces appear (internal, integrations, MCP)
• Regression — Basic agent chat, workspace switching, memory/tasks/lists/tables still work

P2 — Nice to verify

• New integration creation — Follow .claude/commands/create-integration.md, verify auto-discovery
• MCP tools — Still register and work via app.mcp.*

---

Migration

# Pre-merge requirements
git clone https://github.com/OpenCompanyApp/integrations.git ../integrations

# Post-merge
composer install
php artisan migrate
php artisan config:cache
php artisan route:cache
php artisan queue:restart

---

⚠️ Breaking Changes

1. ../integrations/ must exist — App will not boot without it. CI updated accordingly.
2. ToolRegistry API changed — Any code directly calling old methods must use new provider-based API.
3. Direct tool groups reduced — Only tasks, system, agents, memory, lua are direct AI tools. All other tools are Lua-only (lua_exec).
4. Provider registration moved — GLM/Kimi/MiniMax no longer registered in AppServiceProvider. Handled by PrismRelayServiceProvider.

[ruttydm]

Superseded by #6, which merges the integration ecosystem refactor and runtime memory alignment work on the integrated \ branch.