Bot Service

Overview

Port: 4002 The Bot Service handles agent CRUD operations, AI chat via OpenRouter/LangChain, RAG context retrieval from linked knowledge bases, prompt configuration, conversation management, and credit billing.

Endpoints

Agent CRUD

Route	Method	Purpose
`/bots`	POST	Create bot — requires `member`; validates `knowledgeBaseIds` (400 `invalid_knowledge_base_ids`)
`/bots`	GET	List org bots
`/bots/:id`	GET	Get bot (includes linked KBs)
`/bots/:id`	PUT	Update bot (syncs KB links via `knowledgeBaseIds`, validated against the agent’s org)
`/bots/:id`	DELETE	Delete bot
`/bots/:id/usage`	GET	Bot usage stats
`/bots/:id/indexing-status`	GET	Proxies knowledge-service indexing status for this bot

Chat

Route	Method	Purpose
`/bots/:id/chat`	POST	Chat with bot (core endpoint)
`/bots/:id/conversations`	POST	Create conversation (returns welcome message)
`/conversations`	GET	List conversations (filter: botId, userId, platform)
`/conversations/:id`	GET	Get conversation
`/conversations/:id/messages`	GET	Get messages

Prompt Configuration

Route	Method	Purpose
`/bots/:id/prompt-configs`	GET	List all prompt configs for a bot
`/bots/:id/prompt-configs/:type`	GET	Get specific prompt config
`/bots/:id/prompt-configs/:type`	PUT	Create or update prompt config
`/bots/:id/prompt-configs/:type`	DELETE	Remove bot override (falls back to system default)
`/bots/:id/prompt-configs/:type/versions`	GET	Prompt config version history
`/bots/:id/prompt-configs/:type/rollback`	POST	Rollback to a specific version

Variables and Context Tokens (not implemented)

None of these routes exist. They are the designed write paths for sensitive variables and signed context tokens, kept here for the planned verified-variables work (see docs/agentic-development/CHORES.md C-210). Today variables arrive only as variables on POST /bots/:id/chat and the conversation-create routes; contextToken is accepted by the conversation-create schemas but has no effect.

Route (designed, not implemented)	Method	Purpose
`/bots/:id/conversations/:convId/variables`	POST	Set server-side / sensitive variables
`/bots/:id/conversations/:convId/variables`	GET	Get current variables (excludes sensitive)
`/bots/:id/context-token`	POST	Generate signed context token for sensitive variables

Models and Files

Route	Method	Purpose
`/models`	GET	Available AI models (from OpenRouter)
`/models/:id`	GET	Model details
`/attachments`	POST	Upload file attachment
`/analytics/*`	GET	Usage analytics

Knowledge Base Readiness Gate

All paths that make an agent publicly or organizationally “live” verify KB readiness before proceeding:

POST /bots with isDraft: false
PUT /bots/:id when setting isDraft: false
POST /bots/:id/publish
POST /bots/:id/approve
POST /bots/:botId/distribution/publish

The GET /bots/:id/indexing-status endpoint proxies GET /knowledge/agents/:id/indexing-status and returns:

Field	Meaning
`linkedKbCount`	Number of linked KBs
`totalDocuments`	Total documents across linked KBs
`indexedDocuments`	Documents with `processing_status = completed`
`failedDocuments`	Failed documents
`pendingDocuments`	Pending/processing documents
`ready`	`true` when `linkedKbCount > 0` and `indexedDocuments > 0`

If the knowledge service is unreachable, the check is fail-closed and publishing is blocked.

Chat Flow Pipeline

The core chat endpoint (POST /bots/:id/chat) follows this pipeline:

Provider Error Handling

Provider-level failures are mapped to user-friendly messages before reaching the UI. The mapping is centralized in services/bot/src/utils/error-utils.ts via mapProviderError().

Error condition	`code`	User-facing message
OpenRouter 402 / credit-limit / “fewer max_tokens”	`provider_limit_reached`	”This assistant is temporarily unavailable. Please try again later.”
Rate limit / 429	`rate_limit`	”Rate limit exceeded. Please wait a moment and try again.”
Auth failure / 401 / 403	`auth_failed`	”AI provider authentication failed. Please check the API key configuration.”
Model not available	`model_unavailable`	”The selected AI model is not available. Please try a different model in the agent settings.”

The raw provider error message — including any API key URLs — is sanitized by sanitizeProviderMessage() before logging. Streaming chat emits error events as data: { "type": "error", "message": "...", "code": "..." }. Non-streaming chat returns { "error": "...", "code": "..." } when a provider-level failure occurs. Public widget chat and chat-core headless consumers receive the same codes.

Welcome Message Flow

When a conversation is created (POST /bots/:id/conversations):

Create Conversation

Create conversation record in database.

Resolve Variables

Merge variables from the request body and agent defaults. (contextToken is accepted by the schema but has no effect; context tokens are not implemented — C-210.)

Resolve Welcome Config

Welcome is read from bots.widget_config.welcome, not via prompt-resolution. Despite the field’s name it is channel-wide: every channel’s conversation start reads it. If absent or disabled, the conversation returns with no welcome message.

Render and Generate

If no config or enabled=false: return conversation with no welcome message.
If mode='fixed': render content with variables, return directly.
If mode='generated': render prompt template, call LLM, optionally stream response.

Save and Return

Save welcome message as first assistant message. Return { conversationId, welcomeMessage }.

Fixed mode has no cost. Generated mode calls record_external_cost_event() with operation welcome_message_generation.

Prompt Resolution Flow

All prompts resolve via the same three-tier chain:

Look up bot_prompt_configs for (bot_id, prompt_type) WHERE enabled=true
If found -> use bot-level config
If not found -> look up system_prompt_defaults for prompt_type
If not found -> use hardcoded fallback constant (safety net)
Render template with conversation variables via renderPrompt()
mode='fixed': return rendered content
mode='generated': send rendered prompt to LLM, return output

RAG Quality Controls

Control	Threshold/Rule
Initial filter	Chunks with vector score < 0.35 are discarded
Reranking	Hybrid score = 60% vector similarity + 25% text relevance + 15% importance weight
Post-rerank filter	Chunks with combined score < 0.25 are discarded
Document diversity	Max 2 chunks per document
Empty context	If no chunks pass filters, KB context section is omitted

Core Services

Service	Purpose
`bot.service.ts`	Chat orchestration, KB retrieval, reranking, billing
`langchain-chat.service.ts`	LangChain wrapper, conversation memory, LangSmith tracing
`openrouter.service.ts`	OpenRouter API client, model listing
`model-sync.service.ts`	Periodic sync of models from OpenRouter to DB
`file-upload.service.ts`	S3/local file upload with signed URLs
`cloud-storage.service.ts`	S3 + local storage abstraction
`prompt-resolution.service.ts`	Three-tier prompt resolution
`conversation-variables.service.ts`	Variable merge, storage, sensitive variable encryption

Database Tables

Table	Purpose
`bots`	Bot config (name, model, system_prompt, `model_config` JSONB, organization_id, `streaming_enabled`, `widget_config`)
`conversations`	Chat sessions (bot_id, user_id, platform, metadata)
`messages`	Chat messages (conversation_id, role, content)
`message_attachments`	File uploads (access_token, cloud_storage_key)
`bot_versions`	Version history on updates
`models`	AI models with pricing (synced from OpenRouter)
`usage`	Token + cost tracking per conversation
`external_cost_events`	Billing ledger
`agent_builds`	Provisioning build records (agent-build / from-url flow)
`kb_agent_links`	KB-to-bot junction (managed on bot create/update)
`bot_prompt_configs`	Per-agent prompt overrides
`bot_prompt_config_versions`	Version history for bot prompt configs
`system_prompt_defaults`	Platform-wide fallback prompts
`conversation_variables`	Per-conversation variable store (encrypted sensitive vars)

External Integrations

Integration	Config
OpenRouter	`OPENROUTER_API_KEY`, `OPENROUTER_BASE_URL`
Knowledge Service	`KNOWLEDGE_SERVICE_URL` (default: http://localhost:4005)
LangSmith	`LANGSMITH_TRACING`, `LANGSMITH_API_KEY`, `LANGSMITH_PROJECT`
S3 (optional)	`CLOUD_STORAGE_PROVIDER`, `CLOUD_STORAGE_BUCKET`, S3 creds

Critical Patterns

Authentication

Use request.user.organizationId / request.user.id from JWT middleware. NEVER read raw headers.

Billing

Every chat MUST call record_external_cost_event() with provider, operation, cost, orgId, userId. Generated-mode welcome messages also bill.

KB Linking

On bot update, knowledgeBaseIds array replaces all links in kb_agent_links. If frontend sends [], all links are deleted. Every id is validated first (utils/kb-link-validation.ts): it must exist, be in the agent’s organization, and — when its link changes — be editable by the caller, as the knowledge service’s POST /knowledge/kb-access decides. A failure is 400 invalid_knowledge_base_ids and writes nothing; a check that cannot complete is a 503. At most 100 ids per request.

Calling the knowledge service

Every call goes through utils/knowledge-client.ts (knowledgeFetch with a KnowledgeCaller, or knowledgeInternalFetch for /internal/*). It sends the caller’s x-org-role and signs any bearer it mints. CI’s check-knowledge-client.js fails on a KNOWLEDGE_SERVICE_URL/_HOST/_PORT reference, a hard-coded :4005, or a raw fetch/axios call to a /knowledge/ URL anywhere else.

RBAC

checkResourceAccess() before all bot operations.

Graceful Degradation

KB retrieval failures do not block chat — response continues without context.

Prompt Resolution

NEVER read bots.system_prompt directly in new code. Always go through prompt-resolution.service.ts.

Sensitive Variables

NEVER return conversation_variables.sensitive_variables in any API response.

Streaming

Check bot.streaming_enabled AND request.stream === true before streaming any response.

Overview

Services

Architecture

Agent Provisioning API

Deployment

Design System (Neo)

Overview

Endpoints

Agent CRUD

Chat

Prompt Configuration

Variables and Context Tokens (not implemented)

Models and Files

Knowledge Base Readiness Gate

Chat Flow Pipeline

Provider Error Handling

Welcome Message Flow

Prompt Resolution Flow

RAG Quality Controls

Core Services

Database Tables

External Integrations

Critical Patterns

​Overview

​Endpoints

​Agent CRUD

​Chat

​Prompt Configuration

​Variables and Context Tokens (not implemented)

​Models and Files

​Knowledge Base Readiness Gate

​Chat Flow Pipeline

​Provider Error Handling

​Welcome Message Flow

​Prompt Resolution Flow

​RAG Quality Controls

​Core Services

​Database Tables

​External Integrations

​Critical Patterns

Overview

Endpoints

Agent CRUD

Chat

Prompt Configuration

Variables and Context Tokens (not implemented)

Models and Files

Knowledge Base Readiness Gate

Chat Flow Pipeline

Provider Error Handling

Welcome Message Flow

Prompt Resolution Flow

RAG Quality Controls

Core Services

Database Tables

External Integrations

Critical Patterns