179 lines
6.5 KiB
JSON
179 lines
6.5 KiB
JSON
{
|
|
"schemaVersion": "1.0",
|
|
"id": "ai-chatbot-admin-managed",
|
|
"title": "Admin-Managed AI Chatbot",
|
|
"classification": "plugin-candidate",
|
|
"status": "proposed",
|
|
"owner": "feature-integration",
|
|
"description": "Tenant-facing AI chatbot whose provider credentials, browser/runtime policy, and global availability are managed by admin/platform configuration.",
|
|
"rationale": [
|
|
"AI provider keys and browser automation capabilities are sensitive platform resources and should not be stored in tenant-owned settings by default.",
|
|
"Tenant users can consume the chatbot while admin controls provider choice, budgets, allowed models, browser access, and safety policy.",
|
|
"Browser-backed AI work is operationally different from normal request/response UI and should be declared as worker-backed before implementation."
|
|
],
|
|
"codeAreas": [
|
|
"apps/web/app/modules/chatbot",
|
|
"apps/web/app/modules/ai",
|
|
"apps/web/app/routes/admin/ai/*",
|
|
"apps/web/app/routes/admin/chat/*",
|
|
"apps/web/app/routes/app.$tenant/chat/*",
|
|
"apps/web/app/components/ai-elements/*",
|
|
"apps/web/app/utils/html-sanitizer.ts",
|
|
"apps/api/src/app.ts",
|
|
"/v1/ai/upload",
|
|
"apps/worker",
|
|
"packages/queue"
|
|
],
|
|
"dependencies": [
|
|
"core",
|
|
"auth-tenancy",
|
|
"admin-app-shell",
|
|
"rows-entities-runtime"
|
|
],
|
|
"consumers": [
|
|
"plugin-candidates"
|
|
],
|
|
"integration": {
|
|
"ownership": "admin-managed",
|
|
"surfaces": {
|
|
"adminRoutes": [
|
|
"apps/web/app/routes/admin/ai/*",
|
|
"apps/web/app/routes/admin/chat/*",
|
|
"admin settings for provider credentials, model policy, browser policy, and usage limits"
|
|
],
|
|
"tenantRoutes": [
|
|
"apps/web/app/routes/app.$tenant/chat/*",
|
|
"tenant chatbot launcher or embedded assistant surface"
|
|
],
|
|
"publicRoutes": [],
|
|
"apiRoutes": [
|
|
"/v1/ai/upload",
|
|
"streaming chat endpoints",
|
|
"worker enqueue/status endpoints if browser work is async"
|
|
]
|
|
},
|
|
"configuration": {
|
|
"admin": [
|
|
"AI provider API key approved for the deployment region",
|
|
"Allowed model list",
|
|
"Default model",
|
|
"Browser automation enablement",
|
|
"Browser allowlist/denylist policy",
|
|
"Per-tenant feature enablement",
|
|
"Global budget and rate limits"
|
|
],
|
|
"tenant": [
|
|
"Tenant-level enable/disable if admin allows it",
|
|
"Tenant-facing chatbot context and display preferences",
|
|
"Optional tenant knowledge/context selection without provider secrets"
|
|
],
|
|
"environment": [
|
|
"AI_PROCESSING_REGION",
|
|
"MISTRAL_API_KEY",
|
|
"MISTRAL_MODEL",
|
|
"SCALEWAY_API_KEY",
|
|
"SCALEWAY_MODEL",
|
|
"SCALEWAY_BASE_URL",
|
|
"SCALEWAY_REGION",
|
|
"ALEPH_ALPHA_API_KEY",
|
|
"ALEPH_ALPHA_MODEL",
|
|
"ALEPH_ALPHA_BASE_URL",
|
|
"AI_GENERATION_MAX_ESTIMATED_INPUT_COST_CENTS",
|
|
"AI_GENERATION_RATE_LIMIT",
|
|
"AI_GENERATION_RATE_LIMIT_WINDOW_MS",
|
|
"BULLMQ_REDIS_URL",
|
|
"BROWSER_RUNTIME_URL",
|
|
"BROWSER_RUNTIME_API_KEY",
|
|
"BROWSER_SESSION_TIMEOUT_MS"
|
|
],
|
|
"secrets": [
|
|
"AI provider API keys are admin/platform-owned.",
|
|
"Provider keys must never be exposed in tenant routes, tenant JSON loaders, browser bundles, or client-visible config.",
|
|
"Browser session credentials and proxy credentials are worker/platform-owned."
|
|
]
|
|
},
|
|
"workers": {
|
|
"required": true,
|
|
"queues": [
|
|
"toolctrl.ai-chatbot",
|
|
"toolctrl.browser-automation"
|
|
],
|
|
"jobs": [
|
|
"chat-completion",
|
|
"browser-session-run",
|
|
"browser-session-cleanup",
|
|
"usage-flush"
|
|
],
|
|
"notes": [
|
|
"Short text-only chat can stream in request scope, but any browser-backed task must be queue/worker-backed.",
|
|
"Worker jobs must receive scoped tenant/user/context IDs, not raw secrets from tenant input.",
|
|
"Browser jobs must enforce admin-owned allowlist policy before navigation."
|
|
]
|
|
},
|
|
"externalProviders": [
|
|
"deployment-region-ai-provider",
|
|
"browser-runtime"
|
|
],
|
|
"permissions": [
|
|
"admin.ai.configure",
|
|
"admin.ai.providers.update",
|
|
"admin.ai.usage.view",
|
|
"app.ai.chat.use"
|
|
],
|
|
"auditEvents": [
|
|
"admin.ai.provider_key.updated",
|
|
"admin.ai.model_policy.updated",
|
|
"admin.ai.browser_policy.updated",
|
|
"tenant.ai_chatbot.enabled",
|
|
"ai_chatbot.browser_job.started",
|
|
"ai_chatbot.browser_job.completed",
|
|
"ai_chatbot.browser_job.failed"
|
|
],
|
|
"billingImpacts": [
|
|
"AI token usage may need plan gates or usage metering.",
|
|
"Browser runtime usage may need separate metering from text-token usage.",
|
|
"Admin-owned provider keys mean platform billing exposure unless tenant pass-through billing is explicitly designed."
|
|
],
|
|
"uat": [
|
|
"Admin can save provider configuration without exposing the key to tenant responses or client bundles.",
|
|
"Admin can enable/disable the chatbot for a tenant.",
|
|
"Tenant can start a chat only when the feature is enabled and permission allows it.",
|
|
"AI markdown and web-preview surfaces sanitize active HTML and restrict preview iframes to safe HTTP(S) targets.",
|
|
"Browser-backed chat tasks run through a worker queue and enforce admin allowlist policy.",
|
|
"Usage and key-policy changes emit audit events."
|
|
]
|
|
},
|
|
"boundaries": {
|
|
"mustKeep": [
|
|
"Provider secrets remain admin/platform-owned.",
|
|
"Tenant surfaces only receive non-secret feature state and allowed options.",
|
|
"Browser-backed tasks require worker isolation and navigation policy enforcement."
|
|
],
|
|
"mayMoveToPlugin": [
|
|
"All AI/chatbot/browser automation surfaces",
|
|
"Provider-specific AI implementation",
|
|
"Usage metering beyond core billing hooks"
|
|
],
|
|
"mustNotTouch": [
|
|
"Core auth/session logic except permission checks needed by this plugin.",
|
|
"Core billing internals except explicit usage-meter hooks."
|
|
]
|
|
},
|
|
"pruning": {
|
|
"phase": "planning",
|
|
"action": "extract-plugin",
|
|
"notes": [
|
|
"Use this as the reference pattern for admin-managed tenant features that need provider secrets or workers.",
|
|
"Do not implement browser automation in request scope."
|
|
]
|
|
},
|
|
"validation": {
|
|
"source": [
|
|
"docs/agent-playbooks/admin-managed-features.md",
|
|
"docs/agent-playbooks/worker-backed-features.md",
|
|
"docs/agent-playbooks/feature-integration.md"
|
|
],
|
|
"lastReviewed": "2026-05-16"
|
|
}
|
|
}
|