/claim #1301

[!NOTE] Risk: Medium

• Adds a DB migration and changes how MCP tools, chat API keys, Vault, and E2E startup behave.
• Mistakes here could break MCP tool discovery, MCP App rendering, or BYOS/Vault credentials – reviewers should run tests and spot‑check the new flows.

Summary

This PR does two big things:

1. Adds first‑class MCP Apps support (tool metadata and UI resource rendering in chat).
2. Hardens BYOS/Vault flows and E2E/dev tooling so Vault tests and local workflows are reliable.

1. MCP Apps support

1.1 Tool metadata (tools.meta)

• DB migration: 0099_tools_meta_mcp_apps.sql
  • Adds a meta jsonb column to tools to store MCP Apps metadata.
• Backend wiring:
  • Tool schema/model updated to read/write meta.
  • mcp-client, mcp-server routes, McpServerModel, and ToolModel now:
    • Capture MCP tool _meta from discovery.
    • Persist it onto tools.meta.
• Chat tools API:
  • Chat tools API now exposes tool _meta (when present) so the frontend can understand tool‑level metadata for Apps.

1.2 MCP resources/read and UI resource proxy

• MCP gateway:
  • Extends the MCP gateway to support resources/read, not just tools.
• New chat endpoint:
  • Adds /api/chat/agents/:agentId/mcp-app-resource:
    • Given an agent + ui:// URI, finds the corresponding MCP server + catalog item.
    • Calls back into the MCP server to read the resource (e.g. HTML for a UI).
    • Returns the content to the frontend with appropriate MIME type.
• Frontend MCP App rendering:
  • frontend/src/components/chat/mcp-app-frame.tsx:
    • Sandboxed iframe wrapper for MCP App UI.
    • Used by chat to render ui:// tool results safely.

2. BYOS / Vault fixes and reliability

2.1 BYOS Vault chat API keys

• Route: backend/src/routes/chat-api-keys.ts
• Problem before:
  • When BYOS (readonly_vault) was enabled, CreateChatApiKey:
    • Read the API key from Vault.
    • Then called testProviderApiKey (which talks to Anthropic/OpenAI/Gemini).
  • In dev/offline/E2E, this caused 400s and prevented keys from being created, even though Vault was configured correctly.
• Fix:
  • For BYOS/Vault:
    • Read from Vault and fail if the path/key is wrong.
    • Do NOT call external providers in create/update when storing a Vault reference.
    • Store vaultSecretPath#vaultSecretKey in our own secret and rely on:
      • Vault connectivity tests.
      • The “Test Connection” flows.
  • For direct apiKey (non‑BYOS) we still call testProviderApiKey as before.

Result: BYOS/Vault chat API keys can be created and updated even when external LLM endpoints are not reachable, and the E2E tests no longer flake on that path.

2.2 Team Vault folder dialog + controlled inputs

• frontend/src/components/teams/team-vault-folder-dialog.ee.tsx
  • The “Vault Path” textbox is now ref‑aware and uses the actual DOM value when:
    • Testing connection,
    • Saving the team folder.
  • This avoids races where Playwright updated the input but React state wasn’t yet in sync.
• frontend/src/components/ui/input.tsx
  • Updated to forwardRef to the underlying <input>, so:
    • E2E tests and other code can safely use refs on Input.
    • The Vault dialog (and other components) can rely on ref.current.value.

3. Vault E2E and test/dev scripts

3.1 Real Vault E2E runner

New scripts:

• platform/scripts/run-e2e-vault.ps1
• platform/scripts/run-e2e-vault.sh

Behavior:

• Require Docker and a running Docker daemon.
• Free ports 3000, 9000, 8200.
• Start Vault via dev/docker-compose.vault.ee.yml:
  • Wait for http://127.0.0.1:8200/v1/sys/health.
  • Enable KV v2 at secret using dev-root-token.
• Copy platform/.env to backend/.env, wire frontend .env.development.local to http://127.0.0.1:9000.
• Start backend (@backend dev), wait for /health.
• Start frontend (@frontend dev), wait for http://localhost:3000.
• Run only the credentials-with-vault Playwright project.
• Tear everything down: backend, frontend, and archestra-vault container.

3.2 General “E2E with app” runner

Scripts:

• platform/scripts/run-e2e-with-app.ps1
• platform/scripts/run-e2e-with-app.sh

Behavior:

• Backend‑first startup (avoid ECONNREFUSED on 9000).
• Optionally start Vault via Docker for Vault‑related E2E.
• Run a stable subset of E2E projects (setup + chromium‑stable) with known flakies excluded.
• Clean up backend/frontend and Vault afterwards.

3.3 Dev helpers and DB setup

• platform/scripts/SETUP-DATABASE-NOW.ps1
  • One‑shot Postgres + migrations setup, including 0099_tools_meta_mcp_apps.sql.
• platform/scripts/setup-db*.ps1 and scripts/setup-db.sql
  • More granular DB bootstrap scripts for different environments.
• backend/src/standalone-scripts/setup-dev-db.ts
  • TypeScript helper for setting up the dev DB programmatically.
• backend/scripts/dev-with-server.mjs
  • Backend dev script:
    • Clear backend/dist/,
    • Build once with tsdown,
    • Start tsdown --watch and node dist/server.mjs in parallel.

4. E2E tests and feature‑gated MCP flows

4.1 Credentials/Vault E2E

• platform/e2e-tests/tests/ui/credentials-with-vault.ee.spec.ts
  • Stabilized:
    • Secrets manager switch to BYOS_VAULT.
    • Team Vault folder creation/configuration (secret/data/teams).
    • Chat API key creation with Vault secrets (team + personal).
  • For K8S “Self‑hosted (orchestrated by Archestra in K8S)” flows:
    • Tests now call /api/features and skip when orchestrator-k8s-runtime is false.
    • This avoids failing tests in dev environments without a Kubernetes orchestrator configured.
  • Timeouts increased where needed (e.g. chat API key rows and Vault connectivity).

4.2 Vault mock (for constrained environments)

• platform/e2e-tests/mock-vault.mjs
  • Simple Node HTTP server on 8200 that:
    • Implements /v1/sys/health, /v1/secret/data/..., /v1/secret/metadata/... and list/read semantics.
  • Used to run Vault E2E in environments where Docker isn’t available, without changing the main code path.

5. Frontend health and config tweaks

• frontend/src/app/health/route.ts
  • Frontend /health route for environments that health‑check the Next.js app directly.
• Config updates (already present in this branch) align the default backend URL with 127.0.0.1, and tests around config/proxying were adjusted accordingly so local dev and E2E use the same base URLs.

6. Docs

• platform/docs/TESTING.md (new)
  • Documents:
    • DB prerequisites and setup (SETUP-DATABASE-NOW.ps1, setup-db*.ps1, setup-dev-db.ts).
    • How to run unit/integration tests.
    • How to run:
      • Full E2E (run-e2e-with-app.*),
      • Vault E2E only (run-e2e-vault.*),
      • Manual two‑terminal E2E.
    • Helper scripts (dev-for-e2e.*, test-all.ps1, backend dev-with-server.mjs).
    • Troubleshooting tips (ports, DB, migrations, Vault health, sign‑in 500s, etc.).

Test plan

• Unit/integration tests:
  • cd platform && pnpm test -- --run
• Full E2E:
  • cd platform && .\scripts\run-e2e-with-app.ps1 (or ./scripts/run-e2e-with-app.sh)
• Vault E2E only:
  • Ensure Docker Desktop is running.
  • cd platform && .\scripts\run-e2e-vault.ps1 (or ./scripts/run-e2e-vault.sh)
  • Expect: credentials-with-vault project passes; K8S self‑hosted MCP tests show as skipped if orchestrator-k8s-runtime is disabled.