apiVersion: capsule.dev/v0.1
kind: Capsule
name: f4c-bot-service
version: 0.1.0
type: subsystem
purpose:
  summary: 'Manages per-room AI chat sessions, including message history persistence
    and hourly rate limiting, using Cloudflare Durable Objects and Cloudflare AI Gateway.
    It provides an API endpoint for external services to interact with the bot.

    '
  owns:
  - AI chat bot logic and persona ('Luna')
  - Message history storage and management within Durable Objects
  - Hourly rate limiting for AI interactions
  - API endpoint for proxying messages to the bot Durable Object
  does_not_own:
  - Frontend UI for chat messages
  - General room management or participant authentication
  - Real-time communication infrastructure
interfaces:
  provides:
  - kind: http_api
    name: /api/bot
    description: API endpoint for sending user messages to the AI bot and receiving
      replies.
  - kind: event
    name: DurableObject:BotSession
    description: Cloudflare Durable Object for stateful AI bot sessions.
  requires:
  - kind: env
    name: CF_AIG_TOKEN
    description: Authentication token for Cloudflare AI Gateway.
  - kind: env
    name: CF_AI_GATEWAY_BASEURL
    description: Base URL for the Cloudflare AI Gateway (OpenAI-compatible endpoint).
  - kind: env
    name: ROOMS_KV
    description: Cloudflare KV Namespace for rate limiting and checking room existence/bot
      enablement.
  - kind: env
    name: BOT_SESSION
    description: Durable Object Namespace binding for BotSession.
dependencies:
  capsules:
  - name: f4c-room-api
    version: '>=0.1.0'
agent:
  summary_for_ai: 'This capsule implements the AI bot''s core logic and API. Agents
    should focus on improving bot responses, managing AI model integration, or refining
    rate limiting. Pay attention to the `BOT_SYSTEM_PROMPT` and `BOT_MODEL` for AI
    behavior.

    '
  avoid:
  - Introducing direct UI components or client-side logic.
  - Changing the core Durable Object state management without careful consideration
    of data migration.
verification:
  invariants:
  - The bot must maintain per-room message history up to `MAX_HISTORY`.
  - The bot must adhere to `HOURLY_RATE_LIMIT` per room.
  - The `/api/bot` endpoint must correctly route requests to the appropriate `BotSession`
    Durable Object.
x-reuse:
  notes: 'app/src/do/BotSession.ts: `BOT_SYSTEM_PROMPT` defines the bot''s persona
    (''Luna'') and can be customized. `BOT_MODEL` is hardcoded to `workers-ai/@cf/zai-org/glm-4.7-flash`.
    `MAX_HISTORY` and `HOURLY_RATE_LIMIT` are hardcoded. app/src/pages/api/bot.ts:
    `ALLOWED_ORIGINS` is hardcoded. `RATE_LIMIT_WINDOW_S`, `RATE_LIMIT_MAX`, `MAX_MESSAGE_LENGTH`
    are hardcoded. Relies on `ROOMS_KV` for IP rate limiting and checking `botEnabled`
    status from room records.

    '
x-reconstruct:
  install: install.json