legionio 1.4.73 → 1.4.79

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7693068b5190222c508dd07a248424e8f9e1eff77e80059cbd8a4fc81e9e6325
-  data.tar.gz: 43cc0da2efe7d604101ab87426c21b5f8ce677a8c023aeec38e5b91018b515ae
+  metadata.gz: 833830caa5613e077d49c9a67c1dc00b907a473daf7be9033c9389c51546a5e3
+  data.tar.gz: 9c93197f8b0a9ecd0f784598c9b81e98d0158ab03b94d4b822a3d6ef55419868
 SHA512:
-  metadata.gz: a2d75a86b1646113be917a9f8ed17f8f7aa8ffb48ff371db78ee62fbfdba1929d85e675f2bf7d6a5469b077f10370f3d044eb6f5049db353d471f5be1c3cbab5
-  data.tar.gz: 2f00a29a6ddf7be18ee71839b97e1a8aeeb74f2cecd820932447bc574fcfeb595a6adce0d757909bf3e3d68909235fcbb32ad95182192b5471dea0a2f3d39a0e
+  metadata.gz: 4689fa56cc6ad0cfd06f1b836fd36211edeaedacc65306ed888bdc97d36e1d430f5c7c6f3eb65427ff7c234cf1908f2fb14f26f448b8d6f2a414c726011c699f
+  data.tar.gz: 3a127117aba989a57d1e1077e6972a2d32d07c02148fb53eae5c083e8752d509d4a9d84a9db9bb3086292a983e3154d8632e7bca41483a5e9740ccb1769c1ec0

data/.github/workflows/ci.yml

@@ -14,3 +14,16 @@ jobs:
     uses: LegionIO/.github/.github/workflows/release.yml@main
     secrets:
       rubygems-api-key: ${{ secrets.RUBYGEMS_API_KEY }}
+
+  trigger-homebrew:
+    needs: release
+    if: needs.release.outputs.changed == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger daemon build
+        env:
+          GH_TOKEN: ${{ secrets.HOMEBREW_DISPATCH_TOKEN }}
+        run: |
+          gh api repos/LegionIO/homebrew-tap/dispatches \
+            -f event_type=build-daemon \
+            -f "client_payload[legionio_version]=${{ needs.release.outputs.version }}"

data/CHANGELOG.md

@@ -1,5 +1,68 @@
 # Legion Changelog
 
+## [1.4.79] - 2026-03-20
+
+### Added
+- Unified LEX routing layer: auto-expose runner functions as POST endpoints at `/api/lex/{ext}/{runner}/{action}`
+- `Builders::Routes` auto-discovers runner public methods during extension autobuild
+- `Routes::Lex` wildcard handler dispatches through Ingress with JWT + RBAC
+- `GET /api/lex` listing endpoint for route discovery
+- Settings-based configuration at `api.lex_routes` (global enable, per-extension enable, runner/function exclusions)
+- `skip_routes` DSL for runner modules to opt out of auto-route exposure
+- Auto-routes included in OpenAPI spec generation
+- `runner_module` reference stored in builders runner hash for introspection
+
+## [1.4.78] - 2026-03-19
+
+### Added
+- Response headers support in `render_custom_response`: runners can return `response[:headers]` hash for custom HTTP headers
+
+### Removed
+- Legacy `POST /api/hooks/:lex_name/:hook_name` route (superseded by `GET|POST /api/hooks/lex/*` splat routes in v1.4.76)
+- Hardcoded `GET /api/auth/negotiate` Kerberos route (migrated to lex-kerberos hook at `/api/hooks/lex/kerberos/negotiate`)
+- `Routes::AuthKerberos` module and `api/auth_kerberos.rb` file
+
+## [1.4.77] - 2026-03-19
+
+### Added
+- Hardcoded deny list in `Extensions::Permissions` blocking access to `~/.ssh`, `~/.gnupg`, `~/.aws/credentials`
+- Deny list overrides all other permission checks including explicit approvals
+
+## [1.4.76] - 2026-03-19
+
+### Added
+- `Hooks::Base.mount(path)` DSL for extension-derived URL suffixes (e.g., `/callback`)
+- `GET /api/hooks/lex/*` splat route for hook discovery via GET requests
+- `POST /api/hooks/lex/*` splat route with `route_path`-based hook dispatch
+- `Legion::API.find_hook_by_path(path)` for direct route-path lookup in hook registry
+- `route_path` field stored in hook registry entries and returned in `GET /api/hooks` listing
+- Runner-controlled responses: `result[:response]` hash with `:status`, `:content_type`, `:body`
+- `build_payload`, `dispatch_hook`, `render_custom_response` extracted helpers in Routes::Hooks
+
+### Changed
+- `register_hook` now accepts `route_path:` keyword; defaults to `lex_name/hook_name` if omitted
+- `builders/hooks.rb` computes `route_path` from `extension_name/hook_name + mount_path`
+- `extensions/core.rb` passes `route_path:` when calling `Legion::API.register_hook`
+- `GET /api/hooks` listing now includes `route_path` and updated `endpoint` field
+- Removed `Routes::OAuth` (moved OAuth callback to lex-microsoft_teams hook with mount path)
+- `handle_hook_request` refactored into smaller helpers to stay within complexity limits
+
+## [1.4.75] - 2026-03-19
+
+### Added
+- `Legion::Extensions::Catalog` singleton state machine tracking extension lifecycle (registered/loaded/starting/running/stopping/stopped)
+- `Legion::Extensions::Permissions` three-layer file permission model (sandbox, declared paths, auto-approve globs)
+- `GET /api/catalog` and `GET /api/catalog/:name` extension capability manifest endpoints
+- Tier 0 routing in `POST /api/llm/chat` via `Legion::MCP::TierRouter` for LLM-free cached responses
+- Data::Local migrations for extension_catalog and extension_permissions tables
+- Catalog lifecycle wired into extension loader (register/loaded/running/stopping/stopped transitions)
+
+## [1.4.74] - 2026-03-19
+
+### Changed
+- Extracted `Legion::MCP` to dedicated `legion-mcp` gem (v0.1.0)
+- Replaced `mcp` gem dependency with `legion-mcp`
+
 ## [1.4.73] - 2026-03-19
 
 ### Added

data/CLAUDE.md

@@ -9,7 +9,7 @@ The primary gem for the LegionIO framework. An extensible async job engine for s
 
 **GitHub**: https://github.com/LegionIO/LegionIO
 **Gem**: `legionio`
-**Version**: 1.4.70
+**Version**: 1.4.79
 **License**: Apache-2.0
 **Docker**: `legionio/legion`
 **Ruby**: >= 3.4
@@ -46,8 +46,8 @@ Legion.start
       ├── 5.  require legion-cache
       ├── 6.  setup_data         (legion-data, MySQL/SQLite + migrations, optional)
       ├── 7.  setup_rbac         (legion-rbac, optional)
-      ├── 8.  setup_llm          (legion-llm, optional)
-      ├── 9.  setup_gaia         (legion-gaia, cognitive layer, optional)
+      ├── 8.  setup_llm          (legion-llm, AI provider setup + routing, optional)
+      ├── 9.  setup_gaia         (legion-gaia, cognitive coordination layer, optional)
       ├── 10. setup_telemetry    (OpenTelemetry, optional)
       ├── 11. setup_supervision  (process supervision)
       ├── 12. load_extensions    (two-phase: require+autobuild all, then hook_all_actors)
@@ -95,9 +95,10 @@ Legion (lib/legion.rb)
 │   │   └── Nothing    # No-op actor
 │   ├── Builders/      # Build actors and runners from LEX definitions
 │   │   ├── Actors     # Build actors from extension definitions
-│   │   ├── Runners    # Build runners from extension definitions
+│   │   ├── Runners    # Build runners from extension definitions (stores runner_module ref)
 │   │   ├── Helpers    # Builder utilities
-│   │   └── Hooks      # Webhook hook system builder
+│   │   ├── Hooks      # Webhook hook system builder
+│   │   └── Routes     # Auto-route builder: introspects runners, registers POST /api/lex/* routes
 │   ├── Helpers/       # Helper mixins for extensions
 │   │   ├── Base       # Base helper mixin
 │   │   ├── Core       # Core helper mixin
@@ -128,6 +129,7 @@ Legion (lib/legion.rb)
 │   │   ├── Events     # SSE stream (sinatra stream) + ring buffer polling fallback
 │   │   ├── Transport  # Connection status, exchanges, queues, publish
 │   │   ├── Hooks      # List + trigger registered extension hooks
+│   │   ├── Lex        # Auto-routes: `POST /api/lex/*` wildcard + `GET /api/lex` listing
 │   │   ├── Workers    # Digital worker lifecycle (`/api/workers/*`) + team routes (`/api/teams/*`)
 │   │   ├── Coldstart  # `POST /api/coldstart/ingest` — trigger lex-coldstart ingest from API
 │   │   ├── Capacity   # Aggregate, forecast, per-worker capacity endpoints
@@ -142,26 +144,13 @@ Legion (lib/legion.rb)
 │   │   ├── ApiVersion # `/api/v1/` rewrite, Deprecation/Sunset headers
 │   │   ├── BodyLimit  # Request body size limit (1MB max, returns 413)
 │   │   └── RateLimit  # Sliding-window rate limiting with per-IP/agent/tenant tiers
-│   └── hook_registry  # Class-level registry: register_hook, find_hook, registered_hooks
-│                      # Populated by extensions via Legion::API.register_hook(...)
+│   ├── hook_registry  # Class-level registry: register_hook, find_hook, registered_hooks
+│   │                  # Populated by extensions via Legion::API.register_hook(...)
+│   └── route_registry # Class-level registry: register_route, find_route_by_path, registered_routes
+│                      # Populated by Builders::Routes during autobuild
 │
-├── MCP (mcp gem)      # MCP server for AI agent integration
-│   ├── MCP.server     # Singleton factory: Legion::MCP.server returns MCP::Server instance
-│   ├── Server         # MCP::Server builder, tool/resource registration
-│   ├── Tools/         # 35 MCP::Tool subclasses (legion.* namespace)
-│   │   ├── RunTask         # Agentic: dot notation task execution
-│   │   ├── DescribeRunner  # Agentic: runner/function discovery
-│   │   ├── List/Get/Delete Task + GetTaskLogs
-│   │   ├── List/Create/Update/Delete Chain
-│   │   ├── List/Create/Update/Delete Relationship
-│   │   ├── List/Get/Enable/Disable Extension
-│   │   ├── List/Create/Update/Delete Schedule
-│   │   ├── GetStatus, GetConfig
-│   │   ├── ListWorkers, ShowWorker, WorkerLifecycle, WorkerCosts, TeamSummary, RoutingStats
-│   │   └── RbacAssignments, RbacCheck, RbacGrants
-│   └── Resources/
-│       ├── RunnerCatalog   # legion://runners - all ext.runner.func paths
-│       └── ExtensionInfo   # legion://extensions/{name} - extension detail template
+├── MCP (legion-mcp gem)  # Extracted to standalone gem — see legion-mcp/CLAUDE.md
+│   └── (35 tools, 2 resources, TierRouter, PatternStore, ContextGuard, Observer, EmbeddingIndex)
 │
 ├── DigitalWorker      # Digital worker platform (AI-as-labor governance)
 │   ├── Lifecycle      # Worker state machine (active/paused/retired/terminated)
@@ -228,6 +217,10 @@ Legion (lib/legion.rb)
     ├── Pr                 # `legion pr` - AI-generated PR title and description via LLM
     ├── Review             # `legion review` - AI code review with severity levels
     ├── Gaia               # `legion gaia` - Gaia status
+    ├── Llm                # `legion llm` - LLM subsystem status and provider health
+    ├── Detect             # `legion detect scan` - scan environment and recommend extensions
+    ├── Observe            # `legion observe stats` - MCP tool usage statistics from Observer
+    ├── Tty                # `legion tty interactive` - launch rich terminal UI (legion-tty)
     ├── Graph              # `legion graph show` - task relationship graph (mermaid/dot)
     ├── Trace              # `legion trace search` - NL trace search via LLM
     ├── Dashboard          # `legion dashboard` - TUI operational dashboard with auto-refresh
@@ -364,7 +357,7 @@ legion
 
   plan                               # read-only exploration mode (no writes/edits/shell)
     [--model MODEL] [--provider PROVIDER]
-    # Slash commands: /save (writes plan to docs/plans/), /help, /quit
+    # Slash commands: /save (writes plan to docs/work/planning/), /help, /quit
 
   swarm                              # multi-agent workflow orchestration
     start NAME                       # run a workflow from .legion/swarms/NAME.json
@@ -483,11 +476,11 @@ legion
 
 ### MCP Design
 
-- Uses `mcp` gem (~> 0.8): `MCP::Server`, `MCP::Tool`, `MCP::Resource`
-- Transports: `MCP::Server::Transports::StdioTransport`, `MCP::Server::Transports::StreamableHTTPTransport`
-- HTTP transport uses rackup + puma
+Extracted to the `legion-mcp` gem (v0.1.0). See `legion-mcp/CLAUDE.md` for full architecture.
+
 - `Legion::MCP.server` is memoized singleton — call `Legion::MCP.reset!` in tests
 - Tool naming: `legion.snake_case_name` (dot namespace, not slash)
+- Tier 0 routing: PatternStore + TierRouter + ContextGuard for LLM-free cached responses
 
 ## Dependencies
 
@@ -507,7 +500,7 @@ legion
 | `oj` (>= 3.16) | Fast JSON (C extension) |
 | `puma` (>= 6.0) | HTTP server for API |
 | `rackup` (>= 2.0) | Rack server launcher for MCP HTTP transport |
-| `mcp` (~> 0.8) | MCP server SDK |
+| `legion-mcp` | MCP server + Tier 0 routing (extracted gem) |
 | `reline` (>= 0.5) | Interactive line editing for chat REPL |
 | `rouge` (>= 4.0) | Syntax highlighting for chat markdown rendering |
 | `tty-spinner` (~> 0.9) | Spinner animation for CLI loading states |
@@ -539,7 +532,7 @@ rack-test, rake, rspec, rubocop, rubocop-rspec, simplecov
 | `lib/legion/extensions.rb` | LEX discovery, loading, actor hooking, shutdown |
 | `lib/legion/extensions/core.rb` | Extension mixin (requirement flags, autobuild) |
 | `lib/legion/extensions/actors/` | Actor types: base, every, loop, once, poll, subscription, nothing, defaults |
-| `lib/legion/extensions/builders/` | Build actors, runners, helpers, hooks from definitions |
+| `lib/legion/extensions/builders/` | Build actors, runners, helpers, hooks, routes from definitions |
 | `lib/legion/extensions/helpers/` | Mixins: base, core, cache, data, logger, transport, task, lex |
 | `lib/legion/extensions/data/` | Extension-level migrator and model |
 | `lib/legion/extensions/hooks/base.rb` | Webhook hook base class |
@@ -572,16 +565,19 @@ rack-test, rake, rspec, rubocop, rubocop-rspec, simplecov
 | `lib/legion/api/settings.rb` | Settings: read/write with redaction + readonly guards |
 | `lib/legion/api/events.rb` | Events: SSE stream + polling fallback (ring buffer) |
 | `lib/legion/api/transport.rb` | Transport: status, exchanges, queues, publish |
-| `lib/legion/api/hooks.rb` | Hooks: list registered + trigger via Ingress |
+| `lib/legion/api/hooks.rb` | Hooks: list registered + trigger via Ingress; supports custom response headers |
+| `lib/legion/api/lex.rb` | Lex auto-routes: `POST /api/lex/*` wildcard dispatch + `GET /api/lex` listing |
 | `lib/legion/api/workers.rb` | Workers + Teams: digital worker lifecycle REST endpoints (`/api/workers/*`) and team cost endpoints (`/api/teams/*`) |
 | `lib/legion/api/coldstart.rb` | Coldstart: `POST /api/coldstart/ingest` — triggers lex-coldstart ingest runner (requires lex-coldstart + lex-memory) |
 | `lib/legion/api/gaia.rb` | Gaia: system status endpoints |
 | `lib/legion/api/token.rb` | Token: JWT token issuance endpoint |
 | `lib/legion/api/openapi.rb` | OpenAPI: `Legion::API::OpenAPI.spec` / `.to_json`; also served at `GET /api/openapi.json` |
-| `lib/legion/api/oauth.rb` | OAuth: `GET /api/oauth/microsoft_teams/callback` — receives delegated OAuth redirect and stores tokens |
 | `lib/legion/api/capacity.rb` | Capacity: aggregate, forecast, and per-worker capacity endpoints |
 | `lib/legion/api/tenants.rb` | Tenants: listing, provisioning, suspension, quota check |
+| `lib/legion/api/catalog.rb` | Catalog: extension catalog with metadata endpoints |
+| `lib/legion/api/llm.rb` | LLM: provider status and routing configuration endpoints |
 | `lib/legion/api/audit.rb` | Audit: list, show, count, export audit log entries |
+| `lib/legion/api/auth.rb` | Auth: combined token exchange endpoint (`POST /api/auth/token` — JWKS verify + RBAC claims mapper) |
 | `lib/legion/api/auth_human.rb` | Auth: human user authentication endpoints |
 | `lib/legion/api/auth_worker.rb` | Auth: digital worker authentication endpoints |
 | `lib/legion/api/rbac.rb` | RBAC: role listing, permission grants, access checks |
@@ -604,19 +600,12 @@ rack-test, rake, rspec, rubocop, rubocop-rspec, simplecov
 | `lib/legion/tenant_context.rb` | Thread-local tenant context propagation (set, clear, with block) |
 | `lib/legion/tenants.rb` | Tenant CRUD, suspension, quota enforcement |
 | `lib/legion/capacity/model.rb` | Workforce capacity calculation (throughput, utilization, forecast, per-worker) |
-| **MCP** | |
-| `lib/legion/mcp.rb` | Entry point: `Legion::MCP.server` singleton factory, `server_for(token:)` |
-| `lib/legion/mcp/auth.rb` | MCP authentication: JWT + API key verification |
-| `lib/legion/mcp/tool_governance.rb` | Risk-tier tool filtering and invocation audit |
-| `lib/legion/mcp/server.rb` | MCP::Server builder, TOOL_CLASSES array, governance-aware build |
+| **MCP** (extracted to `legion-mcp` gem) | |
 | `lib/legion/digital_worker.rb` | DigitalWorker module entry point |
 | `lib/legion/digital_worker/lifecycle.rb` | Worker state machine |
 | `lib/legion/digital_worker/registry.rb` | In-process worker registry |
 | `lib/legion/digital_worker/risk_tier.rb` | AIRB risk tier + governance constraints |
 | `lib/legion/digital_worker/value_metrics.rb` | Token/cost/latency tracking |
-| `lib/legion/mcp/tools/` | 35 MCP::Tool subclasses (incl. rbac_assignments, rbac_check, rbac_grants) |
-| `lib/legion/mcp/resources/runner_catalog.rb` | `legion://runners` resource |
-| `lib/legion/mcp/resources/extension_info.rb` | `legion://extensions/{name}` resource template |
 | **CLI v2** | |
 | `lib/legion/cli.rb` | `Legion::CLI::Main` Thor app, global flags, version, start/stop/status/check |
 | `lib/legion/cli/output.rb` | `Output::Formatter`: color, tables, JSON mode, ANSI stripping |
@@ -676,16 +665,23 @@ rack-test, rake, rspec, rubocop, rubocop-rspec, simplecov
 | `lib/legion/cli/version.rb` | CLI version display helper |
 | `lib/legion/docs/site_generator.rb` | Static documentation site generator |
 | `lib/legion/cli/memory_command.rb` | `legion memory` subcommands (list, add, forget, search, clear) |
-| `lib/legion/cli/plan_command.rb` | `legion plan` — read-only exploration mode with /save to docs/plans/ |
+| `lib/legion/cli/plan_command.rb` | `legion plan` — read-only exploration mode with /save to docs/work/planning/ |
 | `lib/legion/cli/swarm_command.rb` | `legion swarm` — multi-agent workflow orchestration from `.legion/swarms/` |
 | `lib/legion/cli/commit_command.rb` | `legion commit` — AI-generated commit messages via LLM |
 | `lib/legion/cli/pr_command.rb` | `legion pr` — AI-generated PR title + description via LLM |
 | `lib/legion/cli/review_command.rb` | `legion review` — AI code review with severity levels (CRITICAL/WARNING/SUGGESTION/NOTE) |
 | `lib/legion/cli/gaia_command.rb` | `legion gaia` subcommands (status) |
+| `lib/legion/cli/llm_command.rb` | `legion llm` subcommands (status) — LLM subsystem status and provider health |
+| `lib/legion/cli/detect_command.rb` | `legion detect scan` — scan environment and recommend extensions |
+| `lib/legion/cli/observe_command.rb` | `legion observe stats` — MCP tool usage statistics from Observer |
+| `lib/legion/cli/tty_command.rb` | `legion tty interactive` — launch rich terminal UI (legion-tty interactive shell) |
+| `lib/legion/cli/interactive.rb` | `Interactive` Thor class — shared CLI module for `legion` binary entry point |
+| `lib/legion/cli/config_import.rb` | `legion config import` — import config from external sources |
 | `lib/legion/cli/schedule_command.rb` | `legion schedule` subcommands (list, show, add, remove, logs) |
 | `lib/legion/cli/completion_command.rb` | `legion completion` subcommands (bash, zsh, install) |
 | `lib/legion/cli/openapi_command.rb` | `legion openapi` subcommands (generate, routes); also `GET /api/openapi.json` endpoint |
-| `lib/legion/cli/doctor_command.rb` | `legion doctor` — 10-check environment diagnosis; `Doctor::Result` value object with status/message/prescription/auto_fixable |
+| `lib/legion/cli/doctor_command.rb` | `legion doctor` — 11-check environment diagnosis; `Doctor::Result` value object with status/message/prescription/auto_fixable |
+| `lib/legion/cli/doctor/` | Individual check modules: ruby_version, bundle, config, rabbitmq, database, cache, vault, extensions, pid, permissions, plus result.rb |
 | `lib/legion/cli/telemetry_command.rb` | `legion telemetry` subcommands (stats, ingest) — session log analytics |
 | `lib/legion/cli/auth_command.rb` | `legion auth` subcommands (teams) — delegated OAuth browser flow for external services |
 | `completions/legion.bash` | Bash tab completion script |
@@ -713,8 +709,6 @@ rack-test, rake, rspec, rubocop, rubocop-rspec, simplecov
 | `API::Routes::Relationships` | Fully implemented (backed by legion-data migration 013) |
 | `API::Routes::Chains` | 501 stub - no data model |
 | `API::Middleware::Auth` | JWT Bearer auth middleware — real token validation and API key (`X-API-Key` header) auth both implemented |
-| `MCP::Auth` | JWT + API key authentication for MCP server (HTTP transport) |
-| `MCP::ToolGovernance` | Risk-tier tool filtering + audit — disabled by default, opt-in via settings |
 | `legion-data` chains/relationships models | Not yet implemented |
 
 ## Rubocop Notes
@@ -728,7 +722,7 @@ rack-test, rake, rspec, rubocop, rubocop-rspec, simplecov
 
 ```bash
 bundle install
-bundle exec rspec       # 1433 examples, 0 failures
+bundle exec rspec       # 1499 examples, 0 failures
 bundle exec rubocop     # 418 files, 0 offenses
 ```
 

data/README.md

@@ -14,7 +14,7 @@ Schedule tasks, chain services into dependency graphs, run them concurrently via
          ╰──────────────────────────────────────╯
 ```
 
-**Ruby >= 3.4** | **v1.4.67** | **Apache-2.0** | [@Esity](https://github.com/Esity)
+**Ruby >= 3.4** | **v1.4.78** | **Apache-2.0** | [@Esity](https://github.com/Esity)
 
 ---
 
@@ -461,11 +461,13 @@ legion start
       ├── 4. Transport        (legion-transport — RabbitMQ)
       ├── 5. Cache            (legion-cache — Redis/Memcached)
       ├── 6. Data             (legion-data — database + migrations)
-      ├── 7. LLM              (legion-llm — AI provider setup + routing)
-      ├── 8. Supervision      (process supervision)
-      ├── 9. Extensions       (discover + load 280+ LEX gems, filtered by role profile)
-      ├── 10. Cluster Secret  (distribute via Vault or memory)
-      └── 11. API             (Sinatra/Puma on port 4567)
+      ├── 7. RBAC             (legion-rbac — optional role-based access control)
+      ├── 8. LLM              (legion-llm — AI provider setup + routing)
+      ├── 9. GAIA             (legion-gaia — cognitive coordination layer)
+      ├── 10. Supervision     (process supervision)
+      ├── 11. Extensions      (discover + load 280+ LEX gems, filtered by role profile)
+      ├── 12. Cluster Secret  (distribute via Vault or memory)
+      └── 13. API             (Sinatra/Puma on port 4567)
 ```
 
 Each phase registers with `Legion::Readiness`. All phases are individually toggleable.

data/docs/plans/2026-03-19-hooks-expansion-design.md

@@ -0,0 +1,211 @@
+# Hooks Expansion Design
+
+## Summary
+
+Expand the existing hooks system to support GET + POST, extension-derived URL paths, and runner-controlled responses. Removes hardcoded extension routes from LegionIO (starting with `api/oauth.rb`) by letting extensions own their HTTP surface through the existing `hooks/` convention.
+
+## Problem
+
+Extensions that need HTTP endpoints (OAuth callbacks, webhooks, status pages) currently require hardcoded routes in LegionIO's `api/` directory. The `api/oauth.rb` file knows about Microsoft Teams specifically. This couples LegionIO to individual extensions and bypasses the Ingress pipeline (no RBAC, no audit, no events).
+
+The hooks system already handles inbound webhooks with auto-discovery, verification DSL, and Ingress routing — but it only supports POST and always returns JSON.
+
+## Approach
+
+Expand the existing hooks infrastructure. No new module types, no new DSL classes. Three changes:
+
+1. Add GET alongside POST in `api/hooks.rb`
+2. Add a `mount` class method to `Hooks::Base` for sub-path suffixes
+3. Add response control so runners can return HTML/redirects instead of JSON
+
+## URL Derivation
+
+The full URL is deterministic and non-overridable:
+
+```
+/api/hooks/lex/{extension_name}/{hook_class_name}{mount_suffix}
+     fixed      from module       from class name   optional DSL
+```
+
+- `extension_name` — derived from Ruby module hierarchy. `Legion::Extensions::MicrosoftTeams` becomes `microsoft_teams`. Cannot be overridden.
+- `hook_class_name` — derived from the hook class name. `Hooks::Auth` becomes `auth`. Cannot be overridden.
+- `mount_suffix` — optional, declared via `mount '/callback'` in the hook class. Appended after the class name segment.
+
+Examples:
+
+| Hook class | mount | URL |
+|-----------|-------|-----|
+| `MicrosoftTeams::Hooks::Auth` | `'/callback'` | `/api/hooks/lex/microsoft_teams/auth/callback` |
+| `MicrosoftTeams::Hooks::Webhook` | none | `/api/hooks/lex/microsoft_teams/webhook` |
+| `Github::Hooks::Push` | none | `/api/hooks/lex/github/push` |
+| `Slack::Hooks::Events` | `'/interactive'` | `/api/hooks/lex/slack/events/interactive` |
+
+The extension name prefix acts as a namespace fence — extensions can only define routes under their own name. No collisions.
+
+## HTTP Method Support
+
+Both GET and POST route to the same handler method. The runner receives a normalized request hash:
+
+```ruby
+{
+  http_method: 'GET',
+  params: { code: '...', state: '...' },
+  headers: { 'HTTP_HOST' => '...' },
+  body: nil
+}
+```
+
+For GET requests, `params` comes from query string. For POST, `params` is the parsed body. `body` contains the raw POST body (needed for HMAC verification). `headers` are the Rack-normalized request headers.
+
+The API handler:
+
+```ruby
+app.get '/api/hooks/lex/:lex_name/*' do
+  handle_hook_request(params, request)
+end
+
+app.post '/api/hooks/lex/:lex_name/*' do
+  handle_hook_request(params, request)
+end
+```
+
+Both call the same `handle_hook_request` private method that resolves the hook, verifies, and pipes through `Ingress.run`.
+
+## Response Control
+
+If the runner result hash contains a `:response` key, the API layer renders it directly. Otherwise, the default JSON task response.
+
+```ruby
+# Runner returning a custom response (OAuth callback):
+def auth_callback(code:, state:, **)
+  # ... token exchange logic ...
+  {
+    result: { authenticated: true },
+    response: {
+      status: 200,
+      content_type: 'text/html',
+      body: '<html><body><h2>Authentication complete</h2></body></html>'
+    }
+  }
+end
+```
+
+API handler logic:
+
+```ruby
+result = Ingress.run(...)
+if result[:response]
+  status result[:response][:status] || 200
+  content_type result[:response][:content_type] || 'application/json'
+  result[:response][:body]
+else
+  json_response({ task_id: result[:task_id], status: result[:status] })
+end
+```
+
+The `result` key alongside `response` means the task system still captures the outcome for audit/logging even when the HTTP response is HTML. If `:response` is absent, behavior is identical to today.
+
+## Hooks::Base Changes
+
+One new class method:
+
+```ruby
+class Base
+  class << self
+    def mount(path)
+      @mount_path = path
+    end
+
+    attr_reader :mount_path
+  end
+end
+```
+
+Existing DSL unchanged: `route_header`, `route_field`, `verify_hmac`, `verify_token` all still work. They operate on the request after URL routing, same as today.
+
+For hooks that handle both GET callbacks and POST webhooks on the same path, the existing `route` method can inspect the HTTP method from the payload to decide which runner function to call. Or the runner can handle both in a single method.
+
+## Builder Changes
+
+`builders/hooks.rb` `build_hook_list` currently registers hooks keyed by `"lex_name/hook_name"`. Changes:
+
+- Read `hook_class.mount_path` (nil if not declared)
+- Build the full route path: `"{extension_name}/{hook_name}{mount_path}"`
+- Store the full route path in the registry entry
+
+`find_hook` changes to match against the request splat path instead of discrete lex_name/hook_name params.
+
+## Hook Registry
+
+Current registry on `Legion::API`:
+
+```ruby
+register_hook(lex_name:, hook_name:, hook_class:, default_runner:)
+```
+
+Add `route_path:` to the registration:
+
+```ruby
+register_hook(lex_name:, hook_name:, hook_class:, default_runner:, route_path:)
+```
+
+`find_hook` changes from two-param lookup to splat-path matching:
+
+```ruby
+def find_hook_by_path(path)
+  hook_registry.values.find { |h| h[:route_path] == path }
+end
+```
+
+## Backward Compatibility
+
+- Hooks without `mount` work exactly as before — filename becomes the hook name, URL is `/api/hooks/lex/{ext}/{hook_name}`
+- Old `POST /api/hooks/:lex_name/:hook_name` route stays as deprecated alias pointing to the new handler
+- All existing `Hooks::Base` DSL works unchanged
+- Extensions that don't define hooks are unaffected
+
+## Migration: api/oauth.rb
+
+The hardcoded Microsoft Teams OAuth callback moves to lex-microsoft_teams:
+
+**New file:** `lex-microsoft_teams/hooks/auth.rb`
+
+```ruby
+class Auth < Legion::Extensions::Hooks::Base
+  mount '/callback'
+end
+```
+
+**Runner method** in lex-microsoft_teams handles the callback: receives `code` and `state` params, emits the event, returns HTML response.
+
+**LegionIO:** Remove `require_relative 'api/oauth'` and `register Routes::OAuth` from `api.rb`. Delete or gut `api/oauth.rb`.
+
+## Testing
+
+### LegionIO Specs
+
+- Hooks::Base `mount` sets and reads mount_path
+- Builder reads mount_path, builds correct route_path
+- API handler resolves hook from splat path (GET and POST)
+- API handler renders `:response` when present in runner result
+- API handler returns default JSON when `:response` absent
+- Backward compat: old `/api/hooks/:lex_name/:hook_name` still works
+- Verification (HMAC, token) works on both GET and POST
+
+### lex-microsoft_teams Specs
+
+- Hook class discovered by builder
+- OAuth callback runner handles code+state, returns HTML response
+- Events emitted on successful callback
+
+## Files Changed
+
+| File | Repo | Change |
+|------|------|--------|
+| `extensions/hooks/base.rb` | LegionIO | Add `mount` class method |
+| `extensions/builders/hooks.rb` | LegionIO | Read mount_path, build full route_path |
+| `api/hooks.rb` | LegionIO | Add GET route, splat matching, `handle_hook_request`, response control |
+| `api.rb` | LegionIO | Remove `Routes::OAuth`, add backward compat alias |
+| `api/oauth.rb` | LegionIO | Delete |
+| `hooks/auth.rb` | lex-microsoft_teams | New file |
+| Runner (TBD) | lex-microsoft_teams | OAuth callback handler method |

data/legionio.gemspec

@@ -34,7 +34,7 @@ Gem::Specification.new do |spec|
   spec.bindir        = 'exe'
   spec.executables   = %w[legion legionio]
 
-  spec.add_dependency 'mcp', '~> 0.8'
+  spec.add_dependency 'legion-mcp'
 
   spec.add_dependency 'bootsnap', '>= 1.18'
   spec.add_dependency 'concurrent-ruby', '>= 1.2'

data/lib/legion/api/catalog.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Legion
+  class API < Sinatra::Base
+    module Routes
+      module ExtensionCatalog
+        def self.registered(app)
+          app.get '/api/catalog' do
+            entries = Legion::Extensions::Catalog.all.map do |name, entry|
+              build_catalog_manifest(name, entry)
+            end
+            json_response(entries)
+          end
+
+          app.get '/api/catalog/:name' do
+            name = params[:name]
+            entry = Legion::Extensions::Catalog.entry(name)
+            unless entry
+              halt 404, { 'Content-Type' => 'application/json' },
+                   Legion::JSON.dump({ error: { code: 'not_found', message: "Extension #{name} not found" } })
+            end
+
+            json_response(build_catalog_manifest(name, entry))
+          end
+        end
+      end
+    end
+
+    helpers do # rubocop:disable Metrics/BlockLength
+      def build_catalog_manifest(name, entry)
+        {
+          name:          name,
+          state:         entry[:state].to_s,
+          started_at:    entry[:started_at]&.iso8601,
+          permissions:   build_catalog_permissions(name),
+          runners:       build_catalog_runners(name),
+          known_intents: build_catalog_known_intents(name)
+        }
+      end
+
+      def build_catalog_permissions(name)
+        declared = Legion::Extensions::Permissions.declared_paths(name)
+        {
+          sandbox:     Legion::Extensions::Permissions.sandbox_path(name),
+          read_paths:  declared[:read_paths],
+          write_paths: declared[:write_paths]
+        }
+      rescue StandardError
+        { sandbox: Legion::Extensions::Permissions.sandbox_path(name), read_paths: [], write_paths: [] }
+      end
+
+      def build_catalog_runners(name)
+        return {} unless defined?(Legion::Data) && Legion::Data.respond_to?(:connected?) && Legion::Data.connected?
+
+        ext = Legion::Data::Model::Extension.where(gem_name: name).first
+        return {} unless ext
+
+        ext.runners.to_h do |runner|
+          [runner.values[:name], {
+            methods:     runner.functions.map { |f| f.values[:name] },
+            description: runner.values[:description]
+          }]
+        end
+      rescue StandardError
+        {}
+      end
+
+      def build_catalog_known_intents(name)
+        return [] unless defined?(Legion::MCP::PatternStore)
+
+        matched = Legion::MCP::PatternStore.patterns.select do |_hash, pattern|
+          pattern[:tool_chain]&.any? { |t| t.start_with?(name) }
+        end
+        matched.map do |_hash, pattern|
+          { intent: pattern[:intent_text], tool_chain: pattern[:tool_chain], confidence: pattern[:confidence] }
+        end
+      rescue StandardError
+        []
+      end
+    end
+  end
+end